Skip to main content
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, 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

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: 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

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 apply: about 20 seconds of wait, and at most one call per conversation every 5 minutes.