Set it up
- In app.talqui.chat, open Plugins → WebChat, open the connection and go to the Notificações (Notifications) tab.
- Under Como avisar (How to notify), choose Pelo meu sistema (webhook).
- Fill in your endpoint’s URL and method (
POST,PUTorPATCH). Optionally add up to 10 headers your backend expects, such as an API key, under Cabeçalhos (opcional) (Headers). - Click Salvar webhook (Save webhook). The signing secret (
whsec_…) shows once: copy it to your backend’s secrets now. It never shows again. - Click Enviar teste (Send test). Talqui sends a signed test notification right away and shows the response status.
The request
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:
- Compute the HMAC over the raw body, before any JSON parsing.
- Compare it with the header in constant time.
- 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: HMAC_SHA256(secret, "<tenantID>:<userID>"). Your backend already has that secret, so it can redo the computation:
- the result equals
visitorID(constant-time comparison): theuserIDis genuine, notify that user; - it doesn’t, or the visitor is anonymous: ignore the
userID. Notify throughemailorphoneif you want, or not at all.
Example receivers
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,
429or a5xxis retried, up to 4 attempts, 30 seconds apart, with the sameid. 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-Agentor theTalqui-Webhook-*headers.
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 apply: about 20 seconds of wait, and at most one call per conversation every 5 minutes.