Event subscriptions

​

Event types

​

Events

{
  "id": "evt_3b1f6c2e-5d4a-5b8e-9c7f-0a1b2c3d4e5f",
  "type": "whatsapp.message.received",
  "occurredAt": "2026-09-15T10:00:00.000Z",
  "channelId": "ch_AbCdEf12",
  "channel": { "type": "whatsapp" },
  "data": {
    "messageId": "wamid.HBgMOTcyNTQ1NDM0Mzg0FQIAEhgg",
    "from": "15551234567",
    "contactName": "Dana",
    "timestamp": "2026-09-15T10:00:00.000Z",
    "messageType": "text",
    "text": "Hi there",
    "media": null,
    "interactive": null,
    "context": null
  },
  "raw": { "object": "whatsapp_business_account", "entry": [] },
  "rawOmitted": false
}

{
  "id": "evt_9a8b7c6d-5e4f-5a3b-8c2d-1e0f9a8b7c6d",
  "type": "whatsapp.message.status",
  "occurredAt": "2026-09-15T10:01:40.000Z",
  "channelId": "ch_AbCdEf12",
  "channel": { "type": "whatsapp" },
  "data": {
    "messageId": "wamid.HBgMOTcyNTQ1NDM0Mzg0FQIAERgS",
    "recipient": "15551234567",
    "status": "failed",
    "timestamp": "2026-09-15T10:01:40.000Z",
    "error": { "code": 131047, "title": "Re-engagement message" }
  },
  "raw": { "object": "whatsapp_business_account", "entry": [] },
  "rawOmitted": false
}

​

Create a subscription

curl -X POST https://api.hookmyapp.com/channels/ch_AbCdEf12/subscriptions \
  -H "Authorization: Bearer hmok_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/new-message","events":["whatsapp.message.received"],"label":"New message flow"}'

• url: a public https:// address.
• events: at least one event type the channel supports.
• label: optional, up to 120 characters, shown in your delivery log.
• Up to 25 subscriptions per channel.
• Facebook Page channels do not support event subscriptions yet.

​

List and delete

• GET /channels/{ch}/subscriptions lists a channel’s subscriptions, without secrets.
• DELETE /channels/{ch}/subscriptions/{sub} removes one. Deleting it again is harmless. A delivery already in progress may still arrive once.

​

Verify the signature

import crypto from 'node:crypto';

function isSigned(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return typeof header === 'string' && header.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

​

Delivery and retries

• Events usually arrive within seconds.
• Answer with any 2xx within 10 seconds.
• Any other answer, a redirect or a timeout is retried with growing delays for about 3 hours. After that the event is dropped for that subscription.
• While one subscription’s endpoint keeps failing, deliveries to other subscriptions can be briefly delayed.
• An event can arrive more than once, and events can arrive out of order. Drop duplicates by id; order by occurredAt.
• Every attempt shows in your delivery log with the subscription’s label.
• Your main webhook destination does not change. It keeps receiving what it receives today, and a failing subscription never affects it.

​

Sample events

​

For automation platform builders

• Subscribe (a user turns the trigger on): POST /channels/{ch}/subscriptions with the event type the trigger listens for and your platform’s target URL. Store the returned subscriptionId (and the secret, to verify deliveries).
• Unsubscribe (the trigger is turned off or deleted): DELETE /channels/{ch}/subscriptions/{subscriptionId}.
• Sample data (while the user sets up the trigger): GET /channels/{ch}/events?types=<event type>&limit=3.
• Deduplication: use the event id. The same event always has the same id, including when it is delivered more than once.

​

Errors