Webhooks

Webhooks let your systems react to things that happen in Chatasist — a new conversation, an agent reply, a CSAT rating — without polling the API. You register an HTTPS endpoint, choose the events you care about, and Chatasist sends a signed POST request to that URL whenever one of those events occurs.

Webhooks vs. Automations#

Both send an HTTP request to a URL you control, but they answer different needs. Webhooks tell your system what happened, every time. Automations let the AI agent take an action when it decides one is needed.

Use a webhook when you need to know about every occurrence of something. Use an automation when the agent should judge, mid-conversation, whether to act.

Create a webhook#

Use the Send test button next to an endpoint to deliver a sample ping event and confirm your server is reachable. The last response status code is shown on the endpoint.

How delivery works#

Each delivery is an HTTP POST with a JSON body in this shape:

{
  "event": "message.outgoing",
  "data": { "...": "event-specific payload" },
  "sent_at": "2026-10-09T12:34:56+00:00"
}

Every request carries these headers:

Retries. If your endpoint doesn't return a 2xx status, Chatasist retries up to 4 times with increasing delays (about 10s, 60s, then 300s). Respond quickly with a 2xx and do any heavy work asynchronously — a slow endpoint may time out and be retried.

Verifying signatures#

Chatasist signs the raw request body with your endpoint's secret using HMAC-SHA256 and sends it in the X-Chatasist-Signature header as sha256=<hex digest>. Recompute the digest with your secret and compare — reject the request if it doesn't match.

import crypto from "node:crypto"

// Capture the RAW body for signature verification.
app.post(
  "/webhooks/chatasist",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.get("X-Chatasist-Signature") ?? ""
    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", process.env.CHATASIST_WEBHOOK_SECRET)
        .update(req.body) // raw Buffer
        .digest("hex")

    const ok =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))

    if (!ok) return res.sendStatus(401)

    const { event, data } = JSON.parse(req.body.toString())
    // ... handle the event, then:
    res.sendStatus(200)
  }
)

Events#

Conversations#

{
  "event": "conversation.resolved",
  "data": {
    "id": 456,
    "conversation_id": "a1b2c3",
    "customer_id": 123,
    "channel_id": 7,
    "assignee_id": 9,
    "status": "resolved",
    "priority": 1,
    "survey_rating": null,
    "sentiment": "positive",
    "created_at": "2026-10-09T12:00:00+00:00"
  },
  "sent_at": "2026-10-09T12:34:56+00:00"
}

Messages#

{
  "event": "message.outgoing",
  "data": {
    "id": 9876,
    "chat_id": 456,
    "type": "message",
    "sender_type": "User",
    "sender_id": 9,
    "internal": false,
    "preview": "Hi, thanks for reaching out — I can help with that.",
    "customer": {
      "id": 123,
      "external_customer_id": "crm-55",
      "email": "jane@example.com"
    },
    "created_at": "2026-10-09T12:34:55+00:00"
  },
  "sent_at": "2026-10-09T12:34:56+00:00"
}

Calls#

{
  "event": "call.recording_ready",
  "data": {
    "id": 42,
    "chat_id": 456,
    "type": "video",
    "initiator_type": "User",
    "initiator_id": 9,
    "recording_url": "https://.../recording.mp4",
    "started_at": "2026-10-09T12:10:00+00:00",
    "ended_at": "2026-10-09T12:18:00+00:00"
  },
  "sent_at": "2026-10-09T12:34:56+00:00"
}

Customers#

{
  "event": "customer.identified",
  "data": {
    "id": 123,
    "external_customer_id": "crm-55",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "guest": false,
    "created_at": "2026-10-09T11:00:00+00:00"
  },
  "sent_at": "2026-10-09T12:34:56+00:00"
}

Common use: push notifications#

To notify a customer's mobile app of a new reply, subscribe to message.outgoing. On delivery, match data.customer to a user in your system, look up their device token, and send the push through your own FCM/APNs setup. See the mobile SDK's push guidance for how to avoid duplicate notifications while the app is in the foreground.