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

# Webhooks

> Receba notificações HTTP em tempo real quando eventos ocorrerem em seu locatário Truthlocks.

Webhooks permitem que sua aplicação receba notificações automáticas quando eventos ocorrem em sua conta Truthlocks — por exemplo, quando uma atestação é emitida, uma chave é rotacionada ou uma verificação falha. Em vez de consultar a API para mudanças, seu servidor recebe uma requisição HTTP POST com os detalhes do evento.

## Como funciona

**1. Registrar um endpoint**

Adicione um endpoint de webhook em **Configurações > Webhooks** no [console do inquilino](https://console.truthlocks.com). Forneça uma URL HTTPS publicamente acessível e escolha quais tipos de evento você deseja receber.

**2. Receber eventos**

Quando um evento correspondente ocorre, Truthlocks envia uma solicitação HTTP POST para sua URL com uma carga JSON descrevendo o evento.

**3. Verificar a assinatura**

Cada solicitação inclui uma assinatura HMAC-SHA256 no cabeçalho `X-Truthlocks-Signature`. Verifique-a usando o segredo do endpoint para confirmar que a solicitação veio da Truthlocks.

**4. Responder com 200**

Retorne um código de status HTTP `200` para confirmar o recebimento. Se o seu endpoint falhar ou expirar, o Truthlocks tentará novamente com um backoff exponencial.

## Tipos de eventos

Os eventos são agrupados em categorias. Você pode se inscrever em eventos individuais ou usar um curinga (`attestation.*`) para receber todos os eventos em uma categoria.

| Categoria | Evento | Gatilho |
| :- | :- | :- |
| **Atestados** | `attestation.created` | Um novo atestado é emitido |
| | `attestation.revoked` | Uma atestação é revogada |
| | `attestation.expired` | Uma atestação atinge sua data de expiração |
| | `attestation.superseded` | Uma atestação é substituída por uma versão mais recente |
| **Verificação** | `verification.completed` | Uma verificação é bem-sucedida |
| | `verification.failed` | Uma verificação de validação falha |
| **Emissores** | `issuer.created` | Um novo emissor é registrado |
| | `issuer.updated` | O perfil ou as configurações de um emissor mudam |
| | `issuer.suspended` | Um emissor é suspenso |
| **Chaves** | `key.created` | Uma chave de assinatura é registrada |
| | `key.rotated` | Uma chave de assinatura é rotacionada |
| | `key.revoked` | Uma chave de assinatura é revogada |
| | `key.compromised` | Uma chave é relatada como comprometida |
| **Equipe** | `team.member_invited` | Um convite de equipe é enviado |
| | `team.member_joined` | Um membro da equipe aceita um convite |
| | `team.member_removed` | Um membro da equipe é removido |
| | `team.role_changed` | A função de um membro da equipe é atualizada |
| **Faturamento** | `billing.subscription.created` | Uma nova assinatura é criada |
| | `billing.subscription.updated` | Uma assinatura é modificada |
| | `billing.invoice.created` | Uma nova fatura é gerada |
| | `billing.usage.threshold` | Um limite de uso é atingido |
| **Consumidor** | `consumer.content.protected` | Um consumidor protege novo conteúdo |
| **Sinais de risco** | `risk.signal.created` | Um sinal de risco é ingerido (qualquer caminho de detecção) |
| | `risk.signal.escalated` | Uma pontuação de sinal de risco cruza o limite de revisão automática |
| **Recibos** | `receipt.created` | Um novo recibo é cunhado |
| | `receipt.revoked` | Um recibo é revogado |
| | `receipt.type.created` | Um novo tipo de recibo é criado |
| | `receipt.type.deprecated` | Um tipo de recibo é descontinuado |
| **Segurança** | `security.password_changed` | Um usuário altera sua senha |
| | `security.api_key_compromised` | Uma chave de API é sinalizada como comprometida |
| | `security.suspicious_activity` | Atividade suspeita na conta é detectada |

### Filtros curinga

Use `category.*` para assinar todos os eventos em uma categoria. Por exemplo, `attestation.*` corresponde a `attestation.created`, `attestation.revoked`, `attestation.expired` e `attestation.superseded`.

## Limites de endpoint por plano

O número de endpoints de webhook que você pode criar depende do seu nível de plano:

| Plano | Limite de endpoint |
| :- | :- |
| Grátis | 1 |
| Iniciante | 3 |
| Negócios | 10 |
| Enterprise | 25 |

Precisa de mais endpoints? Entre em contato com seu gerente de conta ou atualize seu plano em **Configurações > Faturamento**.

## Criar um endpoint

1. No console do inquilino, vá para **Configurações > Webhooks**.
2. Clique em **Adicionar endpoint**.
3. Digite um nome, sua URL de destino HTTPS e selecione os tipos de evento que deseja receber.
4. Clique em **Criar**.

O console exibe seu segredo de endpoint uma vez. Copie-o imediatamente — você não poderá recuperá-lo depois.

### Via API

```http Request theme={null}
POST /v1/webhooks/endpoints
X-API-Key: tl_live_...
Content-Type: application/json

{
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "event_filters": ["attestation.*", "verification.completed"]
}
```

```json Response theme={null}
{
  "id": "ep_abc123",
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "status": "active",
  "secret": "whsec_...",
  "event_filters": ["attestation.*", "verification.completed"],
  "created_at": "2026-03-25T12:00:00Z"
}
```

### Listar endpoints

Recupere todos os endpoints de webhook para seu locatário:

```http Request theme={null}
GET /v1/webhooks/endpoints
X-API-Key: tl_live_...
```

Consulte a [referência completa da API](https://docs.truthlocks.com/pt/api-reference/webhooks/list-endpoints.md) para detalhes da resposta.

## Verificando assinaturas

Cada solicitação de webhook inclui um cabeçalho de assinatura para verificação. Sempre verifique as assinaturas antes de processar os eventos.

**Formato da assinatura:**

```
X-Truthlocks-Signature: t=1710000000,v1=a1b2c3d4e5f6...
```

Onde `t` é o timestamp Unix e `v1` é o resumo hexadecimal HMAC-SHA256.

**Etapas de verificação:**

1. Extraia `t` (timestamp) e `v1` (assinatura) do cabeçalho.
2. Rejeite a solicitação se o timestamp tiver mais de 5 minutos.
3. Concatene `{timestamp}.{raw_request_body}` para formar a string de assinatura.
4. Calcule HMAC-SHA256 da string de assinatura usando seu segredo de endpoint.
5. Compare o resumo calculado com `v1` usando uma comparação de tempo constante.

```typescript verify-webhook.ts theme={null}
import crypto from "crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/truthlock", (req, res) => {
  const sigHeader = req.headers["x-truthlocks-signature"] as string;
  if (!sigHeader) return res.status(401).send("Missing signature");

  const parts = Object.fromEntries(
    sigHeader.split(",").map((p) => p.split("=") as [string, string])
  );
  const timestamp = parts["t"];
  const signature = parts["v1"];

  // Reject stale requests (5-minute window)
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return res.status(401).send("Timestamp expired");

  // Compute expected signature
  const signingString = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(signingString)
    .digest("hex");

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log("Received event:", event.type);

  res.status(200).json({ received: true });
});
```

```go verify-webhook.go theme={null}
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)

func verifyWebhook(r *http.Request, secret string) ([]byte, error) {
	sig := r.Header.Get("X-Truthlocks-Signature")
	if sig == "" {
		return nil, fmt.Errorf("missing signature header")
	}

	parts := map[string]string{}
	for _, p := range strings.Split(sig, ",") {
		kv := strings.SplitN(p, "=", 2)
		if len(kv) == 2 {
			parts[kv[0]] = kv[1]
		}
	}

	ts, _ := strconv.ParseInt(parts["t"], 10, 64)
	age := math.Abs(float64(time.Now().Unix() - ts))
	if age > 300 {
		return nil, fmt.Errorf("timestamp expired")
	}

	body, err := io.ReadAll(r.Body)
	if err != nil {
		return nil, err
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(fmt.Sprintf("%d.%s", ts, body)))
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(parts["v1"]), []byte(expected)) {
		return nil, fmt.Errorf("invalid signature")
	}

	return body, nil
}
```

```python verify_webhook.py theme={null}
import hashlib
import hmac
import time
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhooks/truthlock", methods=["POST"])
def handle_webhook():
    sig_header = request.headers.get("X-Truthlocks-Signature", "")
    parts = dict(p.split("=", 1) for p in sig_header.split(","))

    timestamp = parts.get("t", "")
    signature = parts.get("v1", "")

    # Reject stale requests
    if abs(time.time() - int(timestamp)) > 300:
        abort(401, "Timestamp expired")

    # Compute expected signature
    signing_string = f"{timestamp}.{request.get_data(as_text=True)}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        signing_string.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401, "Invalid signature")

    event = request.get_json()
    print(f"Received event: {event['type']}")
    return {"received": True}
```

> [!WARNING]
>
> Sempre use uma função de comparação de tempo constante (como `crypto.timingSafeEqual` ou `hmac.compare_digest`) para evitar ataques de temporização.

## Cabeçalhos da solicitação

Cada entrega de webhook inclui estes cabeçalhos:

| Cabeçalho | Descrição |
| :- | :- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Truthlocks-Webhook-Service/1.0` |
| `X-Truthlocks-Event-Id` | Identificador exclusivo para o evento |
| `X-Truthlocks-Event-Type` | Tipo de evento (por exemplo, `attestation.created`) |
| `X-Truthlocks-Timestamp` | Carimbo de data/hora Unix da tentativa de entrega |
| `X-Truthlocks-Signature` | Assinatura HMAC-SHA256 para verificação |

## Comportamento de nova tentativa

Se o seu endpoint retornar um código de status diferente de 2xx ou não responder em 5 segundos, o Truthlocks tentará novamente a entrega com backoff exponencial:

| Tentativa | Atraso aproximado |
| :- | :- |
| 1ª tentativa | \~1 segundo |
| 2ª tentativa | \~2 segundos |
| 3ª tentativa | \~4 segundos |
| 4ª tentativa | \~16 segundos |
| 5ª tentativa | \~1 minuto |
| 6ª tentativa | \~2 minutos |
| 7ª tentativa | \~5 minutos (máx.) |

Os atrasos incluem até 30% de jitter. Após 8 tentativas totais (1 inicial + 7 retentativas), a entrega é marcada como falha.

Você pode visualizar as tentativas de entrega e os detalhes da falha em **Configurações > Webhooks** clicando em um endpoint, ou consultá-los via API:

```http Request theme={null}
GET /v1/webhooks/endpoints/{id}/deliveries
X-API-Key: tl_live_...
```

Consulte a [referência da API de entregas de lista](https://docs.truthlocks.com/pt/api-reference/webhooks/list-deliveries.md) para detalhes da resposta.

## Rotação de segredos

Se o segredo do seu webhook for comprometido, gire-o imediatamente:

1. No console do inquilino, vá para **Configurações > Webhooks** e clique no endpoint.
2. Clique em **Rotacionar segredo**.
3. Copie o novo segredo — o segredo antigo para de funcionar imediatamente.

Você também pode girar via API:

```http Request theme={null}
POST /v1/webhooks/endpoints/{id}/rotate
X-API-Key: tl_live_...
```

## Testando webhooks

Envie um evento de teste para verificar se seu endpoint está funcionando:

1. No console do inquilino, vá para **Configurações > Webhooks** e clique no endpoint.
2. Clique em **Enviar teste**.
3. Um evento `webhook.test` é enviado para sua URL usando o pipeline completo de assinatura e entrega.

Via API:

```http Request theme={null}
POST /v1/webhooks/test-delivery
X-API-Key: tl_live_...
Content-Type: application/json

{
  "endpoint_id": "ep_abc123",
  "event_type": "webhook.test",
  "payload": { "status": "ok", "source": "test-delivery" }
}
```

Os campos `event_type` e `payload` são opcionais — eles assumem como padrão `webhook.test` e um payload de status básico se omitidos.

## Notificações de sinal de risco

Você pode receber notificações de webhook em tempo real sempre que um sinal de risco for criado por qualquer um dos cinco caminhos de detecção do [Anti-Fraud Identity Firewall](https://docs.truthlocks.com/pt/guides/risk-signals.md) — ingestão direta, normalização de eventos, varredura de deepfake, detecção de ATO e pontuação de velocidade.

Assine `risk.signal.*` para receber todos os eventos de sinal de risco, ou assine `risk.signal.created` ou `risk.signal.escalated` individualmente.

### Exemplo de payload

```json theme={null}
{
  "id": "evt_r1s2k3...",
  "type": "risk.signal.created",
  "created_at": "2027-07-24T09:15:00Z",
  "data": {
    "signal_id": "a1b2c3d4-...",
    "signal_source": "velocity",
    "signal_type": "velocity",
    "risk_score": 72,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f"
  }
}
```

### Respondendo a sinais de risco

Use webhooks de sinal de risco para acionar respostas automatizadas — bloquear uma sessão de usuário, notificar sua equipe de segurança ou escalar para um caso de fraude — sem consultar a API.

```javascript theme={null}
app.post("/webhooks/truthlock", (req, res) => {
  const event = JSON.parse(req.body.toString());

  if (event.type === "risk.signal.created") {
    const { risk_score, subject_id, signal_type } = event.data;

    if (risk_score >= 80) {
      // Critical — block immediately and alert security
      blockSubject(subject_id);
      notifySecurityTeam(event.data);
    } else if (risk_score >= 60) {
      // High — throttle and log for review
      throttleSubject(subject_id);
    }
  }

  res.status(200).json({ received: true });
});
```

> [!NOTE]
>
> Os webhooks de sinal de risco são acionados para sinais criados por todos os cinco caminhos de detecção. O campo `signal_source` no payload informa qual caminho gerou o sinal — `external`, `event_normalization`, `deepfake`, `ato` ou `velocity`.

## Melhores práticas

> [!TIP]
>
> Responda aos webhooks rapidamente. Faça seu processamento pesado assincronamente após retornar uma resposta `200` para evitar timeouts e novas tentativas.

* **Verifique cada assinatura.** Nunca pule a verificação de assinatura, mesmo em desenvolvimento.
* **Use uma fila de mensagens.** Enfileire os eventos recebidos e processe-os em um worker para evitar o bloqueio da resposta HTTP.
* **Lidar com duplicatas.** Use o cabeçalho `X-Truthlocks-Event-Id` para deduplicar eventos em caso de novas tentativas.
* **Monitorar falhas de entrega.** Verifique a aba de entregas no console regularmente para entregas falhas ou mortas.
* **Mantenha os segredos seguros.** Armazene seu segredo de webhook em variáveis de ambiente, não no código-fonte.


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