Skip to main content

​
Lifecycle of an event

From on-chain transfer to your 2xx:

​
How a delivery looks

Every delivery is a single HTTP POST to the webhookUrl you registered on the subscription.
PropertyValue
MethodPOST
Content-Typeapplication/json; charset=utf-8
User-AgentWalletSuite-Webhooks/1.0
BodyOne event envelope, JSON
Signature headersWebhook-Id, Webhook-Timestamp, Webhook-Signature
Example request
POST /your/webhook/path HTTP/1.1
Host: hooks.yourapp.com
Content-Type: application/json; charset=utf-8
User-Agent: WalletSuite-Webhooks/1.0
Webhook-Id: 3f0a8d52-7e14-4b9c-a6d2-c8e1f4b09a7d
Webhook-Timestamp: 1779805371
Webhook-Signature: v1,g0gqp1234EXAMPLEsignatureBASE64==

{"schema_version":"1.0","event_id":"3f0a8d52-7e14-4b9c-a6d2-c8e1f4b09a7d","event_type":"transfer.received","subscription_id":"9b7c1e2a-4f6d-4c3b-8a1e-2d5f7a9c0b13","occurred_at":"2026-05-26T14:22:48.123Z","data":{...}}
Authenticate every delivery by verifying its signature - see the verification guide. Delivery source IPs vary by plan; see Egress IPs.

​
Acknowledgement

Your endpoint acknowledges a delivery by responding with any 2xx status within 18 seconds.
  • Success: any 2xx response - the body is ignored.
  • Failure: anything else - a 3xx (redirects are not followed), 4xx, or 5xx, a connection or TLS error, or no response in time. Failures enter the retry schedule.
Respond first, process async - handler design patterns are in Best Practices.

​
Retry behavior

A delivery that is not acknowledged is retried - with no status-code exceptions - on the following schedule, where each period starts after the failure of the preceding attempt:
  • Immediately (the initial delivery)
  • 30 seconds
  • 2 minutes
  • 10 minutes
  • 1 hour
  • 6 hours
  • 12 hours
  • 24 hours
After the final attempt, the event is permanently abandoned - it will not be delivered again. The full schedule spans roughly 43 hours, and each delay is jittered ±25% so retries don’t bunch up after an outage on your side - treat timings as approximate, not a contract.
If a delivery is critical, make your endpoint resilient enough to acknowledge within one of the eight attempts. Missed state can always be retrieved from the chain or the REST API.
An endpoint that fails persistently is automatically paused. Pausing is separate from per-event abandonment: while paused, the subscription stops receiving deliveries and any pending deliveries are held with their retry budget frozen, so a pause never consumes attempts or abandons the backlog. After a cooldown the subscription resumes automatically and delivers the held events with their remaining attempts. Events that occur while the subscription is paused are not captured - reconcile them via the REST API. See the status lifecycle.

​
Delivery semantics

WalletSuite webhooks are delivered at-least-once, in best-effort order.
  • At-least-once: every event is delivered at least once. In rare cases the same event can arrive again - for example, when your endpoint processed a delivery but its 2xx response was lost in transit, so we retry. Dedupe on Webhook-Id and your handler stays correct (see Idempotency).
  • Best-effort ordering: events are sent in the order they occur, but ordering is not a contractual guarantee - retries can interleave with fresh deliveries. For sequence-sensitive logic, order by occurred_at.
occurred_at is the on-chain event time; the Webhook-Timestamp header is the delivery time, used only for replay protection.

​
Idempotency

Every delivery carries a built-in idempotency key: the Webhook-Id header (= event_id in the payload), stable across all retries of the same event. One check against it gives you exactly-once processing on top of at-least-once delivery:
  • Record each Webhook-Id as you process it.
  • Seen before? Acknowledge with 2xx and skip - the work is already done.
The race-safe claim-then-process implementation is in Best Practices.

​
Egress IPs

Deliveries are authenticated by their signature, not by source IP. Static egress IPs are an Enterprise option. For strict network perimeters, deliveries can originate from a fixed set of addresses in your regional environment (US, EU). The regional IP list is provided during enterprise onboarding. Static IPs are a network control layered on top of signature verification, not a replacement for it.

​
Subscription status lifecycle

A subscription’s status tells you whether it is delivering.
StatusDelivering?Meaning
pendingNot yetMomentary state while a new subscription registers - it flips to active automatically.
activeYesFully registered and delivering events as on-chain transfers occur.
failedNoRegistration failed. Delete the subscription and create a fresh one.
pausedNoApplied automatically to persistently failing endpoints. Resumes automatically after a cooldown.
deletedNoThe subscription was deleted. Create a new subscription to resume.

​
Next steps

Verify Signatures

Authenticate every delivery with Standard Webhooks HMAC-SHA256.

Events & Payloads

The full envelope, field semantics, and transfer.received payload.

Best Practices

Handler design: queues, idempotency stores, and resilient processing.

Troubleshooting

Diagnose subscriptions, delivery failures, and signature mismatches.