Webhooks
How Spare delivers signed events to your server and how they fit with polling.
Webhooks are HTTP callbacks Spare sends to a URL you register. Whenever a payment, consent, mandate, or mandate transaction changes state, Spare POST a signed event to that URL. Your server returns 202 Accepted immediately, then processes the event in the background.
In this guide
- Spare delivers a signed compact JWS, not plain JSON
- You subscribe at the resource level, receiving every event that resource emits
- Return 202 Accepted to confirm receipt: any other status triggers a retry
- Events notify; the API GET on the resource confirms authoritative state
How It Works
Three participants are involved: your application (which registers a subscription), Spare (which delivers events), and your receiver (the HTTPS endpoint that accepts them).
The event body is a compact JWS (RFC 7515) signed with ES256, not plain JSON. Your receiver must read the raw body, verify the signature against Spare's public key set, and only then act on the event data inside.
Resource-Level Subscriptions
Spare subscriptions target a resource type (payment_request, consent, payment, mandate, mandate_transaction), not individual event names. When you subscribe to a resource, Spare delivers every event that resource emits.
This is deliberate. Payment journeys are state machines: if you care about payment.completed, you almost always need payment.failed too. Subscribing at the resource level means you see the full lifecycle. Your handler switches on event.type and ignores the event types it does not need.
Events vs. Polling
| Webhooks | Polling | |
|---|---|---|
| Latency | Low, push delivery | Depends on interval |
| API load | Minimal | Grows with traffic |
| Missed transitions | None if receiver is healthy | Possible between polls |
| Best for | Production | Sandbox, debugging, fallback |
Use polling as a fallback if a webhook is delayed, not as the primary production strategy. The two complement each other.
Webhooks Are Notifications, Not Receipts
The event payload is a lean notification, not a full copy of the resource. After verifying and acknowledging a delivery, fetch the resource from the REST API to confirm authoritative state before taking irreversible actions.
Guides
How Webhooks Work
Subscription model, authentication, request signing, and base URLs.
Event Catalog
Every product, resource, and event name available on UAE today.
Manage Subscriptions
Create, list, update, pause, and delete webhook subscriptions.
Receive Events
Verify the JWS, return 202 Accepted, handle retries, and go live.
Key takeaways
- Spare signs every delivery as a compact JWS. Verify before processing.
- Return
202 Accepted. Any other status, including200, triggers a retry. - Subscribe at the resource level and switch on
event.typein your handler. - Events notify. The API GET on the resource confirms authoritative state.