Event subscriptions

​

Event types

​

Events

{
  "id": "evt_1c2d3e4f-5a6b-5c7d-8e9f-0a1b2c3d4e5f",
  "type": "instagram.message.received",
  "occurredAt": "2026-09-15T10:00:00.123Z",
  "channelId": "ch_IgAbCd12",
  "channel": { "type": "instagram" },
  "data": {
    "messageId": "aWdfZAG1faXRlbToxOkl",
    "from": "1234567890",
    "timestamp": "2026-09-15T10:00:00.123Z",
    "text": "Is this still available?",
    "attachments": [],
    "quickReplyPayload": null
  },
  "raw": { "object": "instagram", "entry": [] },
  "rawOmitted": false
}

{
  "id": "evt_7f6e5d4c-3b2a-5f1e-9d8c-7b6a5f4e3d2c",
  "type": "instagram.comment.received",
  "occurredAt": null,
  "channelId": "ch_IgAbCd12",
  "channel": { "type": "instagram" },
  "data": {
    "commentId": "17900000000000001",
    "mediaId": "18000000000000001",
    "from": { "id": "2345678901", "username": "dana.k" },
    "text": "Love this @acme.store",
    "timestamp": null,
    "parentCommentId": null,
    "isLive": false,
    "mentionsChannel": true
  },
  "raw": { "object": "instagram", "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