Skip to main content

​
Webhooks

DZap webhook deliveries notify production integrations about asynchronous execution updates, transaction status changes, partner fee events, and operational events. Treat every webhook as untrusted until the signature, timestamp, event ID, and payload shape are verified.

​
Delivery headers

Webhook deliveries should include: 
DZap-Event-Id: evt_01J...
DZap-Timestamp: 1717117200
DZap-Signature: v1=<hex_hmac_sha256>
Content-Type: application/json
The signature is an HMAC-SHA-256 over: 
<DZap-Timestamp>.<raw request body>
Use the raw request body bytes, not a parsed and re-serialized JSON object.

​
Verification example

import crypto from 'node:crypto';

export function verifyDZapWebhook({
  body,
  timestamp,
  signature,
  secret,
}: {
  body: Buffer;
  timestamp: string;
  signature: string;
  secret: string;
}) {
  const [version, received] = signature.split('=');
  if (version !== 'v1' || !received) return false;

  const payload = Buffer.concat([
    Buffer.from(timestamp),
    Buffer.from('.'),
    body,
  ]);

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(received, 'hex'),
    Buffer.from(expected, 'hex')
  );
}
Reject requests when the timestamp is older than five minutes, the signature is missing, or the event ID has already been processed.

​
Idempotency

Store DZap-Event-Id before applying side effects. If the same event is delivered again, return 200 OK after confirming it was already handled. This keeps retries safe.

​
Retries

DZap retries failed webhook deliveries with backoff. Your endpoint should return:
  • 2xx after successful processing or idempotent duplicate handling.
  • 4xx when the payload is permanently invalid.
  • 5xx when your system is temporarily unavailable and DZap should retry.

​
Event shape

{
  "id": "evt_01J...",
  "type": "intent.status.updated",
  "createdAt": "2026-05-30T00:00:00Z",
  "data": {
    "intentId": "int_01J...",
    "status": "executed",
    "txHash": "0x..."
  }
}

​
Agent guidance

Agents should not create public webhook endpoints without user approval. When reviewing an integration, check that the webhook handler verifies DZap-Signature, stores DZap-Event-Id, uses the raw body for HMAC verification, and returns 2xx for duplicate deliveries.
Last modified on May 31, 2026