> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook notifications

> Talqui calls your backend with a signed request when a reply arrives and the visitor is away, so you notify them through your own push, email or SMS.

With the **Pelo meu sistema (webhook)** (Through my system) mode, Talqui doesn't send any push. For each reply that should notify an away visitor, it calls your backend, which decides how to reach the person. It covers visitors of your website, of the chat link and of your apps.

## Set it up

1. In [app.talqui.chat](https://app.talqui.chat), open **Plugins → WebChat**, open the connection and go to the **Notificações** (Notifications) tab.
2. Under **Como avisar** (How to notify), choose **Pelo meu sistema (webhook)**.
3. Fill in your endpoint's URL and method (`POST`, `PUT` or `PATCH`). Optionally add up to 10 headers your backend expects, such as an API key, under **Cabeçalhos (opcional)** (Headers).
4. Click **Salvar webhook** (Save webhook). The **signing secret** (`whsec_…`) shows **once**: copy it to your backend's secrets now. It never shows again.
5. Click **Enviar teste** (Send test). Talqui sends a signed test notification right away and shows the response status.

**Gerar nova chave** (Generate new secret) replaces the secret. The old one stops working at once, so update your backend right after.

## The request

```http theme={null}
POST /talqui/webhook HTTP/1.1
Host: api.yourcompany.com
Content-Type: application/json
User-Agent: Talqui-Webhook/1.0
Talqui-Webhook-Id: ntf_7f1c2e4a-9b0d-4c55-8a1e-2f6b3c9d0e11
Talqui-Webhook-Timestamp: 1763215200
Talqui-Webhook-Signature: v1=5d41402abc4b2a76b9719d911017c592ae0f5d4c1e2b3a4f5e6d7c8b9a0f1e2d
```

```json theme={null}
{
  "id": "ntf_7f1c2e4a-9b0d-4c55-8a1e-2f6b3c9d0e11",
  "type": "operator_message",
  "createdAt": "2026-11-15T14:00:00.000Z",
  "tenantID": "1a2b3c4d-…",
  "pluginConnectionID": "5e6f7a8b-…",
  "sessionID": "9c0d1e2f-…",
  "contact": {
    "contactID": "3a4b5c6d-…",
    "visitorID": "b9f2…e41c",
    "userID": "cliente_8812",
    "name": "Ana Souza",
    "email": "ana@example.com",
    "phone": "+5511999990000"
  },
  "message": {
    "messageID": "7e8f9a0b-…",
    "kind": "text",
    "authorName": "Carla Mendes",
    "preview": "Hi Ana, your refund was approved."
  }
}
```

| Field | |
| - | - |
| `id` | The notification. The same value goes in `Talqui-Webhook-Id` and stays the same across retries: use it to ignore duplicates. |
| `type` | Who replied: `operator_message` (a person), `bot_message` (a chatbot or AI agent), `automated_message` (a workflow), or `test` (the **Enviar teste** button). |
| `sessionID` | The conversation. |
| `contact.visitorID` | The visitor's WebChat identity: a random ID for anonymous visitors, or the [`userHash`](https://docs.talqui.chat/guides/chat-sdks/identify-users) for identified users. |
| `contact.userID` | Your own user ID, when your code sent it with `setContactMeta({ user_id })`. **Verify it before use**, see below. |
| `contact.name`, `email`, `phone` | Contact details, or `null`. |
| `message.kind` | `text`, `image`, `audio`, `video`, `file`… |
| `message.authorName` | The operator's full name for `operator_message`, otherwise `null`. |
| `message.preview` | The start of a text reply (up to 140 characters), a label for media ("Enviou uma imagem"), or `null` when the connection hides message content. |

## Verify the signature

Every request is signed with your secret: `Talqui-Webhook-Signature` is `v1=` followed by the hex HMAC-SHA256 of `"<timestamp>.<raw body>"`. Before trusting a request:

1. Compute the HMAC over the **raw** body, before any JSON parsing.
2. Compare it with the header in constant time.
3. Refuse timestamps more than 5 minutes away from your clock, so a captured request can't be replayed later.

## Verify the `userID` (required)

`userID` comes from the visitor's device: your app or page sends it with `setContactMeta`. Anyone can open the chat and declare someone else's ID. **Without this check, a visitor could make your backend send their conversation to another person's phone.**

For identified users, `visitorID` is exactly the [`userHash`](https://docs.talqui.chat/guides/chat-sdks/identify-users#compute-the-userhash-on-your-backend): `HMAC_SHA256(secret, "<tenantID>:<userID>")`. Your backend already has that secret, so it can redo the computation:

* the result equals `visitorID` (constant-time comparison): the `userID` is genuine, notify that user;
* it doesn't, or the visitor is anonymous: ignore the `userID`. Notify through `email` or `phone` if you want, or not at all.

## Example receivers

```js Node.js (Express) theme={null}
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const WEBHOOK_SECRET = process.env.TALQUI_WEBHOOK_SECRET;    // whsec_… from the Notifications tab
const IDENTITY_SECRET = process.env.TALQUI_IDENTITY_SECRET;  // the one you use for userHash

const safeEqual = (a, b) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));

const app = express();

app.post('/talqui/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('Talqui-Webhook-Timestamp') ?? '';
  const signature = req.get('Talqui-Webhook-Signature') ?? '';
  const expected = 'v1=' + createHmac('sha256', WEBHOOK_SECRET).update(`${timestamp}.${req.body}`).digest('hex');

  if (!safeEqual(expected, signature)) return res.sendStatus(401);
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401);

  const notification = JSON.parse(req.body);
  res.sendStatus(204); // answer fast, work after

  const { userID, visitorID } = notification.contact;
  const trusted =
    userID !== null &&
    safeEqual(createHmac('sha256', IDENTITY_SECRET).update(`${notification.tenantID}:${userID}`).digest('hex'), visitorID);

  if (trusted) {
    sendPushToUser(userID, notification.message.authorName ?? 'New reply', notification.message.preview);
  }
});
```

```python Python (Flask) theme={null}
import hashlib, hmac, json, os, time
from flask import Flask, request

WEBHOOK_SECRET = os.environ["TALQUI_WEBHOOK_SECRET"].encode()    # whsec_… from the Notifications tab
IDENTITY_SECRET = os.environ["TALQUI_IDENTITY_SECRET"].encode()  # the one you use for userHash

app = Flask(__name__)

@app.post("/talqui/webhook")
def talqui_webhook():
    timestamp = request.headers.get("Talqui-Webhook-Timestamp", "")
    signature = request.headers.get("Talqui-Webhook-Signature", "")
    body = request.get_data()  # raw bytes
    expected = "v1=" + hmac.new(WEBHOOK_SECRET, f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return "", 401
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return "", 401

    notification = json.loads(body)
    contact = notification["contact"]
    user_id = contact["userID"]
    trusted = user_id is not None and hmac.compare_digest(
        hmac.new(IDENTITY_SECRET, f"{notification['tenantID']}:{user_id}".encode(), hashlib.sha256).hexdigest(),
        contact["visitorID"],
    )

    if trusted:
        send_push_to_user(user_id, notification["message"]["authorName"] or "New reply", notification["message"]["preview"])
    return "", 204
```

## Delivery rules

* **Answer with any 2xx within 5 seconds.** Slower answers count as a failure. Do the heavy work after answering.
* **Retries:** a timeout, a network error, `429` or a `5xx` is retried, up to **4 attempts, 30 seconds apart**, with the same `id`. Any other answer (`3xx`, `4xx`) is final.
* **Redirects aren't followed.** Point the URL at the final address.
* **URL rules:** `https://` only, port 443 or 8443, no credentials in the URL, and a host that resolves to a public address. Private, loopback and cloud-metadata addresses are refused, when saving and again before every request.
* **Headers:** your custom headers can't replace `Content-Type`, `Content-Length`, `Host`, `User-Agent` or the `Talqui-Webhook-*` headers.

Each attempt shows in the **Últimos avisos** (Last deliveries) table with its status (**Entregue**, **Tentando de novo**, **Falhou**: delivered, retrying, failed) and the HTTP status, for 7 days. **Última entrega** (Last delivery) under the URL shows the most recent result.

## Good to know

* In this mode Talqui sends no Firebase push and no browser notification: your backend is the only one notifying, so nobody is notified twice.
* The same [timing rules](https://docs.talqui.chat/guides/push-notifications/overview.md#how-it-works) apply: about 20 seconds of wait, and at most one call per conversation every 5 minutes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.