Webhooks

Webhooks push events to your server as they happen, so you don't have to poll. Register an HTTPS endpoint and CorrectInbox POSTs a JSON body for each event.

Register an endpoint

POST /v1/webhooks

Field	Type	Required	Description
url	string	yes	Your HTTPS endpoint.
events	string[]	no	Events to receive. Omit for all.

curl -X POST https://api.correctinbox.com/v1/webhooks \
  -H "X-API-KEY: $CORRECTINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yourapp.com/hooks/correctinbox", "events": ["message.received", "account.disconnected"] }'

await fetch("https://api.correctinbox.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-KEY": process.env.CORRECTINBOX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://yourapp.com/hooks/correctinbox",
    events: ["message.received", "account.disconnected"],
  }),
});

requests.post(
    "https://api.correctinbox.com/v1/webhooks",
    headers={"X-API-KEY": os.environ["CORRECTINBOX_API_KEY"]},
    json={"url": "https://yourapp.com/hooks/correctinbox", "events": ["message.received", "account.disconnected"]},
)

Event types

Event	Fires when
account.connected	An account finishes linking and is operational.
account.disconnected	An account's session becomes invalid.
message.received	A new inbound message arrives in any chat.
campaign.reply	A lead replies to a campaign.
invitation.accepted	Someone accepts a connection request you sent.

Delivery payload

Every delivery is an HTTPS POST with this envelope:

{
  "id": "evt_6h2k",
  "type": "message.received",
  "created_at": "2026-02-01T18:02:11Z",
  "data": {
    "account_id": "acc_8f21c0",
    "chat_id": "cht_19ab",
    "message": { "id": "msg_09", "from_me": false, "text": "Thursday works!" }
  }
}

Verify deliveries

Each request carries an X-CorrectInbox-Signature header — an HMAC‑SHA256 of the raw body using your webhook's signing secret (shown once when you create the webhook). Recompute it and compare before trusting a payload.

import crypto from "node:crypto";

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

Respond 2xx within a few seconds. CorrectInbox retries failed deliveries with exponential backoff.