Webhooks

​

How webhooks work

​

Register an endpoint

curl -sS -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": "Approvals and redemptions",
    "eventTypes": ["change-request-approved", "change-request-rejected", "redemption-created", "voucher-set-stock-threshold-reached"]
  }'

• The response contains firstSecret and secondSecret, shown once. Store both; see Verifying signatures.
• You can subscribe only to types your roles allow (GET /partner/v1/webhook-event-types); others → 400 data-failed-validation with webhook-event-type-not-allowed.
• Endpoints can be created only while API access is active. At most 10 endpoints with 30 types each.
• Endpoints can be updated, paused (:pause), resumed (:resume) and deleted. While paused nothing is sent; those events are logged as endpoint-disabled and can be replayed for 30 days.
• A change of URL or types is emailed to your owners and technical contact.

​

Endpoint requirements

• https on port 443 or 8443, with a certificate from a public CA and TLS 1.2 or newer.
• Publicly resolvable. Private, loopback, link-local and cloud metadata addresses are refused when you save (422 webhook-url-not-allowed, with more.reason) and again before every delivery.
• Answer with any 2xx within 15 seconds. Redirects are not followed and count as failures. Store the event and process it asynchronously.
• If you filter inbound traffic, allow AllRide’s egress addresses (Network and IP addresses).

​

Payload format

{
  "event": {
    "id": "8d2e4b61-5a3f-4c7e-9b10-2f6a7c8d9e01",
    "type": "redemption-created",
    "timestamp": 1793700902
  },
  "payload": {
    "resource": "redemption",
    "id": 551203,
    "status": "completed",
    "voucherSetId": 4211,
    "voucherId": 7730512,
    "redeemedAt": "2026-11-03T10:15:02Z",
    "voidedAt": null,
    "_links": { "self": { "href": "https://api.voucher.allride.io/provider/v1/redemptions/551203", "type": "application/json" } }
  }
}

​

Delivery guarantees

• At least once: the same event can arrive more than once (after a failed or slow response). Make handlers idempotent by event.id.
• Unordered, possibly late: events can arrive in a different order than they happened. 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. Do not rely on order: use event.timestamp (or the resource’s own timestamps such as voidedAt) to drop stale updates.
• Stored, re-signed, retried: the body is stored when the event occurs and signed at each send, so every attempt and replay has a fresh t in x-signing-signature while the body (and event.id) stays identical. A failed attempt is sent again with backoff, up to 5 attempts in total; a replay re-sends the same stored event with five new attempts, and the log keeps counting (attemptNo, attemptCount, replayCount). See Retries, logs and replay.
• Deliveries are made only while your partner and its API access are active; the endpoint’s deliveriesBlockedReason shows why nothing is sent otherwise. Events of such periods are not delivered later.
• The first attempt is sent within about 30 seconds of the event.

​

Test events

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

​

Related

• Verifying signatures
• Retries, logs and replay
• Event catalog