API reference

Webhooks

Subscribe an HTTPS endpoint to workspace events. Deel Flows POSTs a signed JSON payload whenever a subscribed event happens.

Event types

Field	Type	Description
`message.received`	event	A contact sent your workspace a WhatsApp message.
`contact.opted_in`	event	A contact consented to receive messages (e.g. sent START).
`contact.opted_out`	event	A contact withdrew consent (e.g. sent STOP).

POST/v1/webhooks

Create a subscription. The response includes a whsec_ signing secret — store it; you need it to verify deliveries.

curl

curl -X POST https://app.deelflows.com/api/v1/webhooks \
  -H "Authorization: Bearer df_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/deelflows", "events": ["message.received"] }'

Response 201

{
  "id": "wh-uuid",
  "url": "https://example.com/hooks/deelflows",
  "events": ["message.received"],
  "secret": "whsec_…",
  "enabled": true,
  "createdAt": 1765400000000
}

GET/v1/webhooks

List subscriptions.

DELETE/v1/webhooks/:id

Delete a subscription. Returns 204.

Delivery payload

POST to your URL

{
  "event": "message.received",
  "workspaceId": "9f3c…",
  "timestamp": "2026-06-10T12:00:00.000Z",
  "data": {
    "conversationId": "conv-uuid",
    "messageId": "wamid.…",
    "contactId": "c1a2…",
    "phone": "+15551234567",
    "type": "text",
    "body": "Hi, is the apartment still available?",
    "receivedAt": "2026-06-10T12:00:00.000Z"
  }
}

Verify signatures

Every delivery carries an X-DeelFlows-Signature header: the hex HMAC-SHA256 of the raw request body, keyed with your subscription secret. Verify before trusting the payload:

Node.js

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(secret, rawBody, signatureHeader) {
  const expected = createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Delivery & retries

Your endpoint should respond with a 2xx within 5 seconds. Failed deliveries are retried twice with backoff. Respond fast and process asynchronously if you do heavy work.

These webhooks power the Zapier and Make triggers — if you use those integrations, subscriptions are managed for you automatically.