| name | blnk-webhooks |
| description | Subscribe to Blnk webhooks and transaction hooks securely with HMAC verification and idempotent handlers. Use when handling X-Blnk-Signature, transaction.applied events, PRE/POST hooks, or keeping app state in sync after money movements on either the queued or skip_queue path. |
| metadata | {"author":"blnk","version":"0.2"} |
Webhooks and events
Subscribe safely. Verify signatures. Handle events idempotently.
Webhooks work with both queue modes. Global events fire when ledger state changes whether you posted with skip_queue: false or skip_queue: true. Queueing chooses when the HTTP response is final; it does not turn webhooks on or off.
Pair with the blnk-queueing skill for per-step sync vs async. Use this skill for delivery, security, and handlers.
Quick start
- Configure a global webhook URL in Blnk notification settings.
- On each request: verify
X-Blnk-Signature + X-Blnk-Timestamp (references/security.md).
- Allowlist events you need (references/events.md), especially
transaction.applied / transaction.rejected.
- Dedupe by event/transaction id, then update app state (references/receiver.md).
Queue vs skip_queue
| Path | Flag | Role of webhooks |
|---|
| Async (queued) | skip_queue: false | Primary confirmation. Create often returns QUEUED. Treat applied/rejected (or poll) as the terminal signal before marking money settled in your app. |
| Sync | skip_queue: true | Still delivered. Drive the next step from the HTTP/SDK response. Use webhooks for downstream fan-out, notifications, and secondary systems that should not sit on the request path. |
Same verify + idempotent receiver for both. Do not skip webhooks (or treat them as unused) just because a step is sync.
Details on events and handlers: references/events.md, references/receiver.md. Load blnk-queueing for when to choose each path.
Choose mechanism
| Mechanism | Use for |
|---|
| Global webhooks | System events after state changes (both queue modes) |
| Transaction hooks | PRE/POST interceptors on the request path |
Details: references/global-vs-hooks.md.
Mandatory steps
- Verify signatures → references/security.md
- Subscribe only to needed events → references/events.md
- Build an idempotent receiver → references/receiver.md
- Match confirmation to the path:
- Queued: do not treat create success as final until applied/failed events (or poll)
- Skip queue: treat the response as the next-step outcome; still handle webhooks idempotently for any consumer that listens
Hard rules
- Never process unsigned payloads.
- Never mutate your DB from webhooks without idempotency keys (event id / transaction id / reference).
- Return 2xx quickly after durable accept; do heavy work async if needed.
- Never assume webhooks only apply to
QUEUED posts. Sync posts emit the same lifecycle events.
Docs
