feat: implement robust webhook event system with signed delivery (#77)#615
Open
daatsuka wants to merge 1 commit intorohitdash08:mainfrom
Open
feat: implement robust webhook event system with signed delivery (#77)#615daatsuka wants to merge 1 commit intorohitdash08:mainfrom
daatsuka wants to merge 1 commit intorohitdash08:mainfrom
Conversation
…itdash08#77) - Add WebhookEndpoint and WebhookDelivery SQLAlchemy models - HMAC-SHA256 signing via X-Hub-Signature-256 (GitHub webhook convention) - Exponential-backoff retry: 5 attempts, base 2s (2/4/8/16/32s) - Fire-and-forget delivery via daemon threads (zero API latency impact) - Full CRUD API: POST/GET/PATCH/DELETE /webhooks/ - Delivery audit log endpoint: GET /webhooks/{id}/deliveries - emit_event() integration into expense.created flow - docs/webhooks.md: event catalog, payload schemas, Python/Node.js verification examples Closes rohitdash08#77
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the Webhook Event System — signed, reliable outbound HTTP notifications for key FinMind events.
Why this implementation is optimal
Security — HMAC-SHA256 over X-Hub-Signature-256
This follows the GitHub Webhooks convention, the de-facto OSS standard for signed HTTP callbacks. Using
hmac.compare_digestprevents timing-oracle attacks that a naïve==comparison would expose.Reliability — exponential backoff (5 attempts, base 2 s)
Worst-case total delay is 62 s, which respects typical upstream rate limits while recovering from transient network errors. Delivery state is persisted to Postgres after every attempt so no delivery is silently lost.
Zero API latency impact — background thread per delivery
emit_event()starts a daemon thread and returns immediately. The HTTP response time to the caller is unaffected by webhook delivery latency or failures.Operator visibility — audit log endpoint
GET /webhooks/{id}/deliveriesreturns the last 50 attempts with status codes, error messages, and retry counts — no external tooling needed to debug failed deliveries.Files changed
packages/backend/app/services/webhook.pypackages/backend/app/routes/webhooks.pypackages/backend/app/routes/__init__.py/webhooksblueprintpackages/backend/app/routes/expenses.pyexpense.createdeventpackages/backend/app/config.pywebhook_default_secretsettingdocs/webhooks.mdAcceptance criteria
X-Hub-Signature-256)docs/webhooks.md)Closes #77