Developers · Webhooks
Receive events
Get a signed request when messages arrive, campaigns finish or contacts change.
Codique sends a signed POST to your URL when something happens in the workspace. Register endpoints in EngageAutomation › Outbound webhooks, or with POST /api/v1/outbound-webhooks.
Create the webhook
Give it a name, your HTTPS URL and the events to subscribe to.
Copy the signing secret
It is shown once. Store it next to your other secrets.
Verify every request, then answer 2xx quickly
See the code below.
Events
| Event | When |
|---|---|
message.received | A customer sent a message |
message.sent | A message was sent from the workspace |
conversation.assigned | A conversation was assigned |
conversation.status_changed | A conversation was opened, set pending or closed |
campaign.started · campaign.completed | A campaign began or finished sending |
campaign.delivered · campaign.read · campaign.failed · campaign.replied | A campaign message changed status |
contact.created · contact.updated · contact.field_changed | A contact was added or changed |
order.received | A customer sent an order from your catalog |
automation.triggered | A keyword rule fired its webhook action |
webhook.inbound | One of your inbound webhooks received an event |
workflow.http_completed | A workflow’s HTTP request step finished |
The request
Body
{ "event": "message.received", "data": { "conversation_id": "…", "wa_id": "919876543210", "type": "text", "body": "Hi, where is my order?" }, "sent_at": "2026-11-12T09:30:00.000Z"}| Header | Value |
|---|---|
X-Webhook-Signature-256 | sha256= followed by the HMAC-SHA256 of the raw body, keyed with your secret |
X-Webhook-Event | The event name |
X-Webhook-Delivery-Id | The same on every retry of one delivery. Use it to ignore duplicates. |
X-Webhook-Attempt | 1, 2, 3… |
Verify the signature
Compute the signature over the raw bytes you received, before parsing the JSON, and compare in constant time.
import crypto from "node:crypto";import express from "express";const app = express();app.post("/codique-webhook", express.raw({ type: "application/json" }), (req, res) => { const expected = "sha256=" + crypto .createHmac("sha256", process.env.CODIQUE_WEBHOOK_SECRET) .update(req.body) .digest("hex"); const given = req.get("X-Webhook-Signature-256") ?? ""; const valid = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected)); if (!valid) return res.sendStatus(401); const { event, data } = JSON.parse(req.body.toString("utf8")); res.sendStatus(200); // answer first… queue.add(event, data); // …then do the work});Delivery and retries
- Answer with any 2xx status within 10 seconds. Do slow work after answering.
- Anything else is retried, up to 5 attempts, with a growing delay between them. Deduplicate with
X-Webhook-Delivery-Id. - Every attempt is listed under the webhook’s Deliveries, with the status code your server returned.
- Rotate secret from the webhook’s menu if it is exposed. The old secret stops working at once, so update your server straight after.
Still stuck? Contact us with what you were doing and the exact message you saw.