Webhooks API - InstantCampaign

There are two ways to receive events. They differ in how they are delivered.

	Settings → Webhooks	REST hook (`POST /v1/webhooks/subscribe`)
Set up by	An owner or admin in the dashboard	Your code, with an API key that has `webhooks:manage`
Events	Several per endpoint	One per subscription
URL	Must be `https://`	Any public URL (private and internal addresses are refused)
Signature	Standard Webhooks, when you give the endpoint a secret	None
Retries	3 attempts within seconds, then a schedule of about 34 hours (10 attempts in all)	The same schedule
Disabled after 12 hours of failures	Yes	No
`410 Gone`	Retires the endpoint	Deletes the subscription

Both send the same JSON body:

{
  "id": "msg_…",
  "event": "EMAIL_BOUNCED",
  "timestamp": "2026-09-10T09:30:00.000Z",
  "teamId": "…",
  "data": { "email": "jane@example.com", "messageId": "…", "provider": "postmark", "type": "Permanent", "reason": "550", "occurredAt": "2026-09-10T09:29:58.000Z" }
}

Your endpoint has 10 seconds to answer with any 2xx. GET /v1/webhooks/events lists every event type you can subscribe to. For double opt-in, LIST_SUBSCRIPTION_CONFIRMED is sent once for each list a confirmation click activates, with data of { "contactId", "email", "listId", "listName" }. CONTACT_CONFIRMED ({ "contactId", "email" }) is sent only when the contact itself goes from pending to active. See Webhooks.

Subscribing a REST hook

curl -X POST https://instantcampaign.ai/api/v1/webhooks/subscribe \
  -H "Authorization: Bearer ic_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "CONTACT_CREATED", "targetUrl": "https://hooks.example.com/instantcampaign" }'

The response is 201 { "id": "…" }. Subscribing the same event and URL again returns the same id. To remove the subscription, call DELETE /v1/webhooks/{id}.

Verifying signatures

Endpoints registered under Settings → Webhooks with a secret receive these headers:

webhook-id: the message ID. It stays the same across retries, so use it to deduplicate.
webhook-timestamp: Unix seconds.
webhook-signature: v1,<base64 HMAC-SHA256> of "{webhook-id}.{webhook-timestamp}.{raw body}".
X-Signature-256: the legacy header, sha256=<hex HMAC-SHA256 of the raw body>.

If the secret starts with whsec_, base64-decode the rest to get the HMAC key. Otherwise the key is the secret’s UTF-8 bytes. Endpoints without a secret receive no signature headers.

import crypto from "node:crypto";

function verify(secret, headers, rawBody) {
  const key = secret.startsWith("whsec_")
    ? Buffer.from(secret.slice(6), "base64")
    : Buffer.from(secret, "utf8");
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // reject stale deliveries
  const expected = crypto.createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64");
  return headers["webhook-signature"]
    .split(" ")
    .some((sig) => {
      const value = sig.replace(/^v1,/, "");
      return value.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected));
    });
}

Every delivery also carries X-Webhook-Event and X-Webhook-Attempt.

Retries and disabling

For dashboard endpoints, delivery is tried three times in a row, 1 and 2 seconds apart. After that it is retried on a schedule of +5 min, +30 min, +2 h, +5 h, +8 h, +8 h and +10 h. A 429 reschedules the delivery without counting it as a failure. An endpoint that keeps failing for more than 12 hours is disabled until you re-enable it in Settings → Webhooks. The full delivery schema, with every header and payload field, is in Settings → API reference in the app.

​Subscribing a REST hook

​Verifying signatures

​Retries and disabling

Subscribing a REST hook

Verifying signatures

Retries and disabling