Webhooks overview

This document provides detailed technical information for developers integrating with Chatway Webhooks, including event schemas, delivery behavior, security, retries, and best practices.

Chatway sends HTTP POST requests to your configured HTTPS endpoint when a subscribed event occurs.

• Webhooks are event-driven, near real-time, and use at-least-once delivery.
• Configure webhooks from the Chatway app under Settings → Developer Tools → Webhooks.
• Your endpoint must respond with any 2xx status within the configured timeout.

Replying to a visitor message

For the full end-to-end tutorial (subscribe to message.received, verify the signature, read data.conversation.id, and call POST /messages), start with Quickstart → Receive a message and send a reply in the sidebar.

Endpoint requirements

Request headers

Every webhook request includes the following headers:

Content-Type: application/json
X-Chatway-Event: message.received
X-Chatway-Webhook-Id: 9f3c2a1b-4d5e-6f70-8a9b-0c1d2e3f4a5b
X-Chatway-Delivery-Id: del_456
X-Chatway-Delivery-Attempt: 1
X-Chatway-Timestamp: 1785933000
X-Chatway-Signature: sha256=3c9f5e...

Signature verification

Chatway signs each request using HMAC SHA256.

Signature generation

signed_payload = timestamp + "." + raw_request_body
HMAC_SHA256(secret, signed_payload)

The header value is prefixed with sha256=. The timestamp is the value of X-Chatway-Timestamp.

Verification steps

1. Read the raw request body before JSON parsing.
2. Extract X-Chatway-Signature and X-Chatway-Timestamp.
3. Reject requests whose timestamp is older than 300 seconds (recommended).
4. Compute HMAC SHA256 over {timestamp}.{raw_body} using your webhook secret.
5. Compare using a constant-time comparison.

Example (Node.js + Express)

const crypto = require("crypto");
const express = require("express");

const app = express();

// Preserve raw body for signature verification (required).
app.post(
  "/webhooks/chatway",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const secret = process.env.CHATWAY_WEBHOOK_SECRET;
    const signature = req.headers["x-chatway-signature"];
    const timestamp = req.headers["x-chatway-timestamp"];
    const rawBody = req.body; // Buffer

    if (!verifyChatwaySignature(rawBody, signature, timestamp, secret)) {
      return res.status(401).send("Invalid signature");
    }

    res.status(200).send("ok");
  },
);

function verifyChatwaySignature(rawBody, signatureHeader, timestampHeader, secret) {
  if (!signatureHeader || !timestampHeader || !secret) {
    return false;
  }

  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) {
    return false;
  }

  const toleranceSeconds = 300;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) {
    return false;
  }

  const signedPayload = `${timestamp}.${rawBody.toString("utf8")}`;
  const expected = crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");
  const expectedHeader = `sha256=${expected}`;

  const expectedBuffer = Buffer.from(expectedHeader);
  const actualBuffer = Buffer.from(signatureHeader);

  if (expectedBuffer.length !== actualBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuffer, actualBuffer);
}

Example (PHP)

function verifyChatwaySignature(
    string $rawBody,
    ?string $signatureHeader,
    ?string $timestampHeader,
    string $secret,
    int $toleranceSeconds = 300
): bool {
    if ($signatureHeader === null || $signatureHeader === '' || $timestampHeader === null || $timestampHeader === '') {
        return false;
    }

    $timestamp = filter_var($timestampHeader, FILTER_VALIDATE_INT);
    if ($timestamp === false) {
        return false;
    }

    if (abs(time() - $timestamp) > $toleranceSeconds) {
        return false;
    }

    $signedPayload = $timestamp.'.'.$rawBody;
    $expected = 'sha256='.hash_hmac('sha256', $signedPayload, $secret);

    return hash_equals($expected, $signatureHeader);
}

// Laravel example
$rawBody = $request->getContent();
$signature = $request->header('X-Chatway-Signature');
$timestamp = $request->header('X-Chatway-Timestamp');
$secret = config('services.chatway.webhook_secret');

if (! verifyChatwaySignature($rawBody, $signature, $timestamp, $secret)) {
    abort(401, 'Invalid webhook signature.');
}

Event payload structure

All webhook payloads share a common envelope:

{
    "id": "evt_1234567890abcdef1234567890abcdef",
    "event": "message.received",
    "data": {
        "message": {
            "id": "679f5ba4-3cbf-42eb-86dc-63566cec6b58",
            "content": "Hello, I need help",
            "attachments": [],
            "created_at": "2026-02-04T10:31:12Z"
        },
        "conversation": {
            "id": "750c42a1-1ce1-40ae-beba-4cc66f2b1023",
            "channel": "website",
            "status": "open",
            "widget_name": "Main site widget",
            "identifier": "wdg_abc123"
        },
        "visitor": {
            "id": "bfc39f4b-e8aa-4e1c-8e6a-162a5d869702",
            "name": "John Doe",
            "email": "[email protected]",
            "phone": "+1XXXXXXXXXX"
        }
    },
    "occurred_at": "2026-02-04T10:31:12Z",
    "version": "2026-09"
}

Field reference

Common types, optional fields, and normalized channel values used across events.

Envelope

Conversation

Agent

Visitor contact

Contact source

Assigned by

Removed by

Resolved by

Message

Attachment

Contact updated

Custom data

Limits

Idempotency & retries

• Use the envelope field id (evt_…) to detect duplicate processing of the same business event. It stays the same across HTTP retries to your endpoint.
• X-Chatway-Delivery-Id identifies a single HTTP attempt (del_…) and changes on each retry.
• X-Chatway-Delivery-Attempt is the attempt counter (1 through 4).
• occurred_at in the JSON body is fixed when the event is first dispatched and does not change on retry.

Timeout & processing requirements

Chatway enforces a strict 4-second timeout for webhook deliveries. If your endpoint does not respond within 4 seconds, the delivery is marked as failed and retried according to the retry policy.

Delivery & retry policy

Retry conditions

• Timeout
• Network error
• HTTP 5xx response

No retry

• HTTP 4xx responses (including 410 Gone) are not retried for that delivery attempt.
• Returning 410 does not automatically disable your webhook subscription; turn it off in Settings → Developer Tools → Webhooks if needed.

Retry schedule

1. Immediate
2. +1 minute
3. +5 minutes
4. +15 minutes

Chatway makes up to 4 delivery attempts. After the final failure, the delivery is marked as failed.

Required behavior

• Respond immediately with a 2xx HTTP status code.
• Do not perform heavy processing before sending the response.
• Acknowledge receipt first, then process the payload asynchronously.
• Verify X-Chatway-Signature and X-Chatway-Timestamp on every request.
• Handle duplicate deliveries idempotently using the envelope id field (evt_…), not X-Chatway-Delivery-Id.