Service Webhook

The Service Webhook notifies your external system whenever a conversation is finished in Tartini. On each closure, Tartini sends a JSON POST to the configured URL, containing the conversation’s and contact’s data. Optionally, the payload can include the summary generated by Tino, the message history, and the CSAT score. The setting is at Configurações > Integrações > Webhooks > Finalização de Atendimento (Settings > Integrations > Webhooks > Service Completion) (talk.saninternet.com/settings/webhooks).

The trigger fires when the conversation is actually finished. This includes manual closing by the agent, automatic closing due to inactivity, and closing after the CSAT evaluation (with or without a customer response).

Configuration

Turn on the webhook

In Configurações > Integrações > Webhooks > Finalização de Atendimento, turn on the Ativar webhook (Enable webhook) switch.

Enter the destination URL

Your system’s endpoint that will receive the POST. Enter the full URL, including the protocol (http:// or https://).

Generate the signing secret

Click Gerar novo secret (Generate new secret) and store the value securely. It will be used to validate the authenticity of each delivery.

Choose the payload content

Conversation and contact are always sent. You can also include the summary generated by Tino, the message history, and the CSAT score.

Set the relevance filter (optional)

With Registrar apenas atendimentos relevantes (Only log relevant services) turned on, trivial conversations (such as a greeting with no follow-up) aren’t sent to your system.

Test the delivery

The Testar webhook (Test webhook) button sends a test delivery to the configured URL, to validate the integration before you turn it on.

Identifying the Customer: the External ID

For your system to know which customer the service belongs to, every Tartini contact has an ID externo (External ID) field: a free-form code that references the customer in your system (for example, their ID in your ERP or CRM). The agent sets this value in the contact’s details panel, inside the Inbox. Once filled in, it follows the contact through every future closure and arrives in the payload as contact.externalId.

When the ID externo isn’t filled in, contact.externalId arrives as null. The payload also carries contact.phoneNumber.

Payload Format

{
  "event": "conversation.finished",
  "version": "v1",
  "requestId": "f3a1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sentAt": "2026-06-12T15:40:49.716Z",
  "data": {
    "conversation": {
      "id": "c0a8012e-7d3b-4f1a-9e2c-5b6d8f0a1c3e",
      "createdAt": "2026-06-12T14:02:11.000Z",
      "closedAt": "2026-06-12T15:40:49.000Z",
      "closeReason": "Dúvida resolvida pelo atendente",
      "attendant": { "id": "...", "name": "João Atendente" },
      "sector": { "id": "...", "name": "Suporte" },
      "channel": { "id": "...", "type": "ROOKIE", "name": "whatsapp-principal" }
    },
    "contact": {
      "id": "...",
      "name": "Camila Ribeiro",
      "phoneNumber": "5511999999999",
      "externalId": "ERP-12345"
    },
    "summary": {
      "text": "Cliente entrou em contato com dúvida sobre fatura...",
      "score": 9.2,
      "generatedAt": "2026-06-12T15:41:30.000Z"
    },
    "csat": {
      "rating": 5,
      "comment": "Atendimento excelente!",
      "respondedAt": "2026-06-12T15:43:02.000Z"
    },
    "messages": [
      { "sender": "USER", "content": "Oi, tenho uma dúvida sobre minha fatura", "sentAt": "2026-06-12T14:02:11.000Z" }
    ]
  }
}

Special Fields

Field	Meaning
`summary: null`	Summary disabled in the configuration.
`csat: { rating: null }`	The customer didn’t respond to the evaluation before the time limit.
`contact.externalId: null`	No External ID set for the contact.
`messages: null`	Message history disabled in the configuration.

When the summary generated by Tino is enabled, the delivery waits for the summary to be generated and may lag a few minutes behind the conversation’s closure.

Delivery and Response

The POST is sent with Content-Type: application/json.
Your endpoint must respond with a 2xx status to confirm receipt.

Headers Sent

Header	Content
`X-Webhook-Event`	Event name (`conversation.finished`).
`X-Webhook-Signature`	Body signature: `sha256=<HMAC-SHA256(raw body, secret)>`.
`X-Request-Id`	Unique identifier for the delivery.

Validating the Signature

Every delivery is signed with HMAC-SHA256 using the configured secret, sent in the X-Webhook-Signature header. Requests with an invalid signature must be rejected.

const crypto = require('crypto');

// use o corpo bruto (antes do JSON.parse) para calcular o HMAC
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const esperado =
    'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');

  const recebido = req.headers['x-webhook-signature'] || '';
  const valido =
    recebido.length === esperado.length &&
    crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));

  if (!valido) return res.status(401).end();

  const evento = JSON.parse(req.body);
  res.status(200).end();
});

import hmac, hashlib
from flask import Flask, request

@app.post('/webhook')
def webhook():
    corpo = request.get_data()  # corpo bruto
    esperado = 'sha256=' + hmac.new(SECRET.encode(), corpo, hashlib.sha256).hexdigest()
    recebido = request.headers.get('X-Webhook-Signature', '')

    if not hmac.compare_digest(recebido, esperado):
        return '', 401

    evento = request.get_json()
    return '', 200

<?php
$corpo = file_get_contents('php://input'); // corpo bruto
$esperado = 'sha256=' . hash_hmac('sha256', $corpo, $secret);
$recebido = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($esperado, $recebido)) {
    http_response_code(401);
    exit;
}

$evento = json_decode($corpo, true);
http_response_code(200);

The secret never travels in the requests. If it leaks, generate a new one on the configuration screen and save. The next deliveries will immediately start using the new value.

Overview

Concepts

Endpoints

Webhooks and API

Service Webhook

Configuration

Identifying the Customer: the External ID

Payload Format

Special Fields

Delivery and Response

Headers Sent

Validating the Signature

​Configuration

​Identifying the Customer: the External ID

​Payload Format

​Special Fields

​Delivery and Response

​Headers Sent

​Validating the Signature

Configuration

Identifying the Customer: the External ID

Payload Format

Special Fields

Delivery and Response

Headers Sent

Validating the Signature