Skip to main content

​
Recovery Flow

​
When to Run Recovery

  • Missing expected event within your SLA.
  • Signature verification failures due to deployment/config changes.
  • Suspected delivery disruptions.
  • Compact payload received with truncated payload indicator.

​
Recovery Steps

  1. Query your local event store by merchant_reference or transaction_id.
  2. Fetch latest transaction state via GET /transactions/{id} or GET /transactions/reference/{merchant_reference}.
  3. Inspect local webhook log state with GET /webhooks/events.
  4. Inspect per-event delivery telemetry with GET /webhooks/events/{event_id}.
  5. Replay a known event with POST /webhooks/events/{event_id}/replay when redelivery is required.
  6. Reconcile final status and revenue via transaction and revenue endpoints.

​
Compact Payload Handling

If you receive a compact payload marker (compact_payload / payload_truncated):
  1. Treat event as valid envelope notification.
  2. Fetch canonical transaction status from read endpoints.
  3. Continue normal reconciliation path.

​
Replay Guidance

  • Replay only when your consumer missed or rejected a previously emitted event.
  • Replayed events preserve the original webhook id, so your dedupe logic must still treat them as the same logical event.
  • After replay, confirm progress with GET /webhooks/events/{event_id}.
  • Start with GET /transactions/{id} or GET /transactions/reference/{merchant_reference} when business state matters more than delivery state.
  • Use GET /webhooks/events to find the relevant event if you know the transaction or reference but not the webhook id.
  • Use GET /webhooks/events/{event_id} before replay so you can confirm whether the delivery issue is still active.
  • Replay only the specific missed event you need; do not treat replay as a substitute for periodic reconciliation.

​
Duplicate Handling

  • Use webhook id as your dedupe key.
  • Reprocessing the same event must be safe and no-op.