Webhooks

​

How webhooks work

1. Something happens in the platform: a voucher is redeemed, a Redemption Link runs out, a voucher set becomes available in your catalog, an invoice is issued.
2. AllRide renders the event for your partner (the consumer view of the resource) and stores it, with a stable event.id, for every webhook endpoint of yours that subscribes to its type. For an active endpoint the delivery appears in your delivery log at once as PENDING and the send is queued; for a paused endpoint it is stored as FAILED with endpoint-disabled and can be replayed after you resume the endpoint.
3. Your endpoint verifies the x-signing-signature header, answers 2xx within 15 seconds and processes the event afterwards.
4. Any other outcome is a failed attempt; the stored event is sent again with backoff, up to 5 attempts in total. The delivery ends as DELIVERED (a 2xx) or FAILED (the last attempt failed, or no request could be sent; lastErrorCode says why), see Retries, logs and replay.

​

Register an endpoint

curl -X POST "$VOUCHER_API_BASE_URL/partner/v1/webhook-endpoints" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"url\": \"$WEBHOOK_URL\",
    \"description\": \"Redemption notifications\",
    \"eventTypes\": [\"redemption-created\", \"redemption-voided\"]
  }"

• eventTypes holds 1 to 30 unique types that your partner may subscribe to; any other type fails with 400 data-failed-validation and the constraint webhook-event-type-not-allowed. List webhook event types returns the types you can use.
• Billing types (invoice-*, payment-failed, payment-method-deactivated) need view-consumer-billing, and price-terms-* types need view-consumer-pricing, held by the user or API key that creates or changes the endpoint. Without it, every write on such an endpoint answers 403 missing-permission.
• A partner has at most 10 endpoints (webhook-endpoint-limit-reached).
• Update replaces eventTypes as a whole. Pause and resume stop and restart deliveries; events that occur while an endpoint is paused are logged as not delivered and can be replayed within 30 days of the event (resume the endpoint first). Delete is final.
• Owners and your technical contact receive an email when an endpoint is created or its URL or event types change.

​

Endpoint requirements

• HTTPS only, on port 443 or 8443, with a certificate that validates. Plain HTTP is refused.
• Publicly resolvable. URLs that resolve to private, loopback, link-local or cloud metadata addresses are refused when you save them (422 webhook-url-not-allowed) and again at send time.
• Answer 2xx within 15 seconds. Acknowledge first, then do the work asynchronously (for example through your own queue). Any other status, a timeout or a connection error counts as a failure.
• No redirects. AllRide does not follow 3xx responses; a redirect counts as a failure.
• Allow AllRide’s egress addresses if your firewall filters inbound traffic. They are published in Network and IP addresses.
• Verify every request with the x-signing-signature header before you trust the body (Verifying signatures).

​

Payload format

{
  "event": {
    "id": "3f1c9a52-7b4e-4d21-9c6a-0e5d8b2f4a17",
    "type": "redemption-voided",
    "timestamp": 1793692800
  },
  "payload": {
    "resource": "redemption",
    "id": 6017,
    "status": "voided",
    "voucherSetId": 2030,
    "redeemedAt": "2026-10-21T17:42:10.120Z",
    "voidedAt": "2026-11-03T08:00:00Z",
    "voidReason": "Customer cancelled the order",
    "_links": {
      "self": { "href": "https://api.voucher.allride.io/consumer/v1/redemptions/6017", "type": "application/json" }
    }
  }
}

​

Delivery guarantees

• At least once. An event can arrive more than once, for example after a timeout or a replay. Make handlers idempotent: deduplicate on event.id.
• Unordered, possibly late. Events can arrive in any order: retries arrive later than newer events, and events are stored before they are sent, so they are never silently dropped: if a send is delayed, an automatic sweep re-queues a delivery never attempted after about 10 minutes, or last attempted more than 30 minutes ago, so it may arrive late. A delivery that still cannot be sent after 3 re-queues becomes FAILED with delivery-stalled and can be replayed. Use event.timestamp (or the resource’s own timestamps) to drop stale updates, and re-fetch the resource when the order matters.
• Stored, retried, replayable. Each event is stored before it is sent. A failed attempt is sent again with backoff (about 30 seconds growing to 10 minutes), up to 5 attempts in total; then the delivery is FAILED and no longer retried, but you can replay it while it is in the delivery log, 30 days after the event. A replay re-sends the same stored event with the same event.id and five new attempts; the log keeps counting (attemptNo, attemptCount, replayCount).
• Signed at each send. The body is stored at event time and signed when it is sent, so every attempt and replay carries a fresh t and fresh signatures while the body (including event.id and event.timestamp) stays byte for byte the same.

​

Test events

curl -X POST "$VOUCHER_API_BASE_URL/partner/v1/webhook-endpoints/11069:send-test-event" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "message": "Hello from the integration test" }'

{
  "event": { "id": "0c5b7e2d-91a4-4f38-b6d2-7e3a1f9c0b54", "type": "webhook-endpoint-test", "timestamp": 1793610900 },
  "payload": { "resource": "webhook-endpoint", "id": 11069, "message": "Hello from the integration test" }
}

​

Related

• Verifying signatures
• Retries, logs and replay
• Event catalog
• Network and IP addresses
• Idempotency