Webhooks & Event Notifications

Webhooks provide a push-based mechanism for event delivery over HTTP. This is intended for backend systems that need to react to events without maintaining persistent connections.

Use webhooks when you want event-driven automation over standard HTTP. Use WebSockets when you need continuous streams.

---

Event types

Webhook events are generated for defined trigger conditions.

Supported categories include:

• Price threshold crossings

• Wallet balance changes

• Large transaction detection

• Market state transitions

Events are generated only when conditions are met, reducing unnecessary noise.

---

Delivery model

Webhook events are delivered as HTTP POST requests containing structured JSON payloads. Each payload includes metadata such as event type, timestamp, and triggering condition.

Delivery behavior includes:

• Automatic retries with backoff

• Limited retry attempts

• Delivery status tracking

Failed deliveries do not block other events.

---

Reliability & ordering

Webhooks prioritize reliability over ordering guarantees. Events may be delivered out of order in rare failure scenarios. Consumers should treat each event as independently valid.

Consumer guidance (recommended)

Respond fast

• Acknowledge quickly (HTTP 2xx) after basic validation.

• Push heavy work to a queue or background job runner.

Assume duplicates

Retries can result in the same event being delivered more than once.

Design handlers to be idempotent:

• Use a dedupe key if present in the payload.

• Otherwise, dedupe using stable fields (event type + timestamp + trigger condition).

Secure the endpoint

Keep your webhook consumer hardened:

• Use HTTPS.

• Authenticate requests at your edge (token, allowlist, or gateway policy).

• Validate payload structure before processing.