Skip to main content

What are Webhooks?

Webhooks allow you to receive real-time HTTP notifications when trading events occur on your account, eliminating the need to poll the API for order status updates.
Webhooks are the recommended way to track order execution and trade activity. They provide real-time updates and reduce API load.

Supported Events

Webhook Configuration

Webhook setup for Daya Pro is support-managed. Contact support@daya.co to set up or update Pro webhook endpoints and event subscriptions. When requesting setup, include:
  1. Webhook URL (must be HTTPS)
  2. Events to subscribe to
  3. Environment and Pro account details
Webhook URLs must use HTTPS in production. HTTP is only allowed for local development testing.

HTTP Headers

All webhook requests include the following headers:

Webhook Payload

All webhook events follow this structure:

Common Fields

event_id
string
Unique identifier for this event (UUID format)Use for: Idempotency (deduplicate multiple deliveries)
type
string
Event typeValues: order.created, order.filled, order.partially_filled, order.cancelled, order.rejected, trade.executed, deposit.completed, crypto.deposit.completed
timestamp
string
When event occurred (RFC3339 timestamp)
data
object
Event-specific data (varies by event type)

Event-Specific Payloads

Sent when: New order accepted by matching engine
Next steps: Monitor for order.filled, order.partially_filled, or order.cancelled

Delivery Guarantees

Webhooks may be delivered multiple times. Your endpoint must handle duplicate deliveries using event_id for idempotency.
Events may arrive out of order. Use created_at timestamps to order events client-side.
If your endpoint returns non-2xx status or times out, Daya retries with exponential backoff:After 10 failed attempts, delivery is marked as failed and the webhook may be automatically disabled.
Your endpoint must respond within 30 seconds. Longer responses will timeout and trigger retries.
Webhooks are automatically disabled after 10 consecutive delivery failures. Contact support to re-enable a disabled Pro webhook endpoint.
There is no manual redispatch endpoint in this version. Use Get Webhook Deliveries to inspect delivery logs and retry status.

Webhook Verification

All webhooks include an HMAC-SHA256 signature in the X-Webhook-Signature header with a sha256= prefix. Always verify signatures to prevent spoofing.
See Webhook Verification for implementation details.

Implementing a Webhook Endpoint

Required Response

Your endpoint must:
  1. Verify signature (see Verification)
  2. Return 2xx status to acknowledge receipt
  3. Process quickly (< 10 seconds) or queue for async processing

Example Implementation

Best Practices

1

Verify signatures

Always verify X-Webhook-Signature to prevent spoofing attacks. Remember to strip the sha256= prefix before comparing.
2

Handle idempotency

Use event_id to deduplicate. Store processed event IDs in your database.
3

Return 200 quickly

Acknowledge receipt immediately (< 1 second). Queue heavy processing asynchronously.
4

Handle out-of-order delivery

Events may arrive out of order. Use timestamp field and order status to reconcile.
5

Reconcile with API

Periodically call List Orders to reconcile state in case webhooks are missed.

Testing Webhooks

Local Testing

For local development, use tools like ngrok:
Use ngrok’s web interface (http://localhost:4040) to inspect webhook payloads during development.

Troubleshooting

Possible causes:
  • Firewall blocking Daya’s IPs
  • Endpoint returning non-2xx status
  • SSL certificate issues
Fix: Check endpoint logs, ensure HTTPS, verify firewall rules
Expected behavior: At-least-once delivery means duplicates are possibleFix: Implement idempotency using event_id
Cause: Endpoint taking > 30 seconds to respondFix: Return 200 immediately, queue processing asynchronously
Cause: Wrong secret, payload manipulation, or not stripping sha256= prefixFix: Verify you’re using correct webhook secret and stripping the sha256= prefix from the X-Webhook-Signature header before comparing

Next Steps

Webhook Events

Detailed event schemas

Signature Verification

Implement HMAC verification