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

> Reciba notificaciones HTTP en tiempo real cuando ocurran eventos en su inquilino de Truthlocks.

Los webhooks permiten que su aplicación reciba notificaciones automáticas cuando ocurren eventos en su cuenta de Truthlocks; por ejemplo, cuando se acuña una atestación, se rota una clave o falla una verificación. En lugar de sondear la API en busca de cambios, su servidor recibe una solicitud HTTP POST con los detalles del evento.

## Cómo funciona

**1. Registrar un endpoint**

Añada un punto final de webhook en **Configuración > Webhooks** en la [consola del inquilino](https://console.truthlocks.com). Proporcione una URL HTTPS accesible públicamente y elija qué tipos de eventos desea recibir.

**2. Recibir eventos**

Cuando ocurre un evento coincidente, Truthlocks envía una solicitud HTTP POST a su URL con una carga JSON que describe el evento.

**3. Verificar la firma**

Cada solicitud incluye una firma HMAC-SHA256 en el encabezado `X-Truthlocks-Signature`. Verifíquela usando el secreto del endpoint para confirmar que la solicitud provino de Truthlocks.

**4. Responder con 200**

Devuelve un código de estado HTTP `200` para acusar recibo. Si tu endpoint falla o excede el tiempo de espera, Truthlocks reintenta con retroceso exponencial.

## Tipos de eventos

Los eventos se agrupan en categorías. Puede suscribirse a eventos individuales o usar un comodín (`attestation.*`) para recibir todos los eventos de una categoría.

| Categoría | Evento | Disparador |
| :- | :- | :- |
| **Atestaciones** | `attestation.created` | Se acuña una nueva atestación |
| | `attestation.revoked` | Una atestación es revocada |
| | `attestation.expired` | Una atestación alcanza su fecha de vencimiento |
| | `attestation.superseded` | Una atestación es reemplazada por una versión más reciente |
| **Verificación** | `verification.completed` | Una verificación se realiza correctamente |
| | `verification.failed` | Falla una verificación |
| **Emisores** | `issuer.created` | Se registra un nuevo emisor |
| | `issuer.updated` | El perfil o la configuración de un emisor cambian |
| | `issuer.suspended` | Un emisor es suspendido |
| **Claves** | `key.created` | Se registra una clave de firma |
| | `key.rotated` | Se rota una clave de firma |
| | `key.revoked` | Se revoca una clave de firma |
| | `key.compromised` | Se informa que una clave está comprometida |
| **Equipo** | `team.member_invited` | Se envía una invitación al equipo |
| | `team.member_joined` | Un miembro del equipo acepta una invitación |
| | `team.member_removed` | Se elimina un miembro del equipo |
| | `team.role_changed` | Se actualiza el rol de un miembro del equipo |
| **Facturación** | `billing.subscription.created` | Se crea una nueva suscripción |
| | `billing.subscription.updated` | Se modifica una suscripción |
| | `billing.invoice.created` | Se genera una nueva factura |
| | `billing.usage.threshold` | Se alcanza un umbral de uso |
| **Consumidor** | `consumer.content.protected` | Un consumidor protege contenido nuevo |
| **Señales de riesgo** | `risk.signal.created` | Se ingiere una señal de riesgo (cualquier ruta de detección) |
| | `risk.signal.escalated` | Una puntuación de señal de riesgo cruza el umbral de revisión automática |
| **Recibos** | `receipt.created` | Se acuña un nuevo recibo |
| | `receipt.revoked` | Se revoca un recibo |
| | `receipt.type.created` | Se crea un nuevo tipo de recibo |
| | `receipt.type.deprecated` | Se desaprueba un tipo de recibo |
| **Seguridad** | `security.password_changed` | Un usuario cambia su contraseña |
| | `security.api_key_compromised` | Una clave de API es marcada como comprometida |
| | `security.suspicious_activity` | Se detecta actividad sospechosa en la cuenta |

### Filtros comodín

Use `category.*` para suscribirse a cada evento de una categoría. Por ejemplo, `attestation.*` coincide con `attestation.created`, `attestation.revoked`, `attestation.expired` y `attestation.superseded`.

## Límites de endpoint por plan

El número de puntos finales de webhook que puede crear depende de su nivel de plan:

| Plan | Límite de puntos finales |
| :- | :- |
| Gratuito | 1 |
| Starter | 3 |
| Negocio | 10 |
| Enterprise | 25 |

¿Necesita más endpoints? Póngase en contacto con su gerente de cuenta o actualice su plan en **Configuración > Facturación**.

## Creación de un endpoint

1. En la consola del inquilino, vaya a **Configuración > Webhooks**.
2. Haga clic en **Agregar punto de conexión**.
3. Ingrese un nombre, su URL de destino HTTPS y seleccione los tipos de eventos que desea recibir.
4. Haga clic en **Crear**.

La consola muestra su secreto de endpoint una vez. Cópielo inmediatamente; no podrá recuperarlo más tarde.

### A través de la 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 puntos finales

Recuperar todos los endpoints de webhook para su inquilino:

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

Consulte la [referencia completa de la API](https://docs.truthlocks.com/es/api-reference/webhooks/list-endpoints.md) para obtener detalles de la respuesta.

## Verificación de firmas

Cada solicitud de webhook incluye un encabezado de firma para verificación. Siempre verifique las firmas antes de procesar los eventos.

**Formato de firma:**

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

Donde `t` es la marca de tiempo Unix y `v1` es el resumen hexadecimal HMAC-SHA256.

**Pasos de verificación:**

1. Extraiga `t` (marca de tiempo) y `v1` (firma) del encabezado.
2. Rechace la solicitud si la marca de tiempo tiene más de 5 minutos de antigüedad.
3. Concatene `{timestamp}.{raw_request_body}` para formar la cadena de firma.
4. Calcule HMAC-SHA256 de la cadena de firma usando su secreto de punto final.
5. Compare el resumen calculado con `v1` usando una comparación de tiempo 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]
>
> Utilice siempre una función de comparación de tiempo constante (como `crypto.timingSafeEqual` o `hmac.compare_digest`) para evitar ataques de temporización.

## Encabezados de la solicitud

Cada entrega de webhook incluye estos encabezados:

| Encabezado | Descripción |
| :- | :- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Truthlocks-Webhook-Service/1.0` |
| `X-Truthlocks-Event-Id` | Identificador único para el evento |
| `X-Truthlocks-Event-Type` | Tipo de evento (por ejemplo, `attestation.created`) |
| `X-Truthlocks-Timestamp` | Marca de tiempo Unix del intento de entrega |
| `X-Truthlocks-Signature` | Firma HMAC-SHA256 para verificación |

## Comportamiento de reintento

Si su endpoint devuelve un código de estado que no sea 2xx o no responde en 5 segundos, Truthlocks reintenta la entrega con retroceso exponencial:

| Intento | Retraso aproximado |
| :- | :- |
| 1er reintento | \~1 segundo |
| 2do reintento | \~2 segundos |
| 3er reintento | \~4 segundos |
| Cuarto reintento | \~16 segundos |
| Quinto reintento | \~1 minuto |
| Sexto reintento | \~2 minutos |
| Séptimo reintento | \~5 minutos (máx.) |

Los retrasos incluyen hasta un 30% de fluctuación. Después de 8 intentos totales (1 inicial + 7 reintentos), la entrega se marca como fallida.

Puede ver los intentos de entrega y los detalles de fallas en **Configuración > Webhooks** haciendo clic en un punto final, o consultarlos a través de la API:

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

Consulte la [referencia de API de entregas de lista](https://docs.truthlocks.com/es/api-reference/webhooks/list-deliveries.md) para obtener detalles de la respuesta.

## Rotación de secretos

Si su secreto de webhook se ve comprometido, rótelo inmediatamente:

1. En la consola del inquilino, vaya a **Configuración > Webhooks** y haga clic en el punto de conexión.
2. Haga clic en **Rotar secreto**.
3. Copie el nuevo secreto — el secreto antiguo deja de funcionar inmediatamente.

También puede rotar a través de la API:

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

## Probando webhooks

Envíe un evento de prueba para verificar que su endpoint esté funcionando:

1. En la consola del inquilino, vaya a **Configuración > Webhooks** y haga clic en el punto de conexión.
2. Haga clic en **Enviar prueba**.
3. Se envía un evento `webhook.test` a su URL utilizando la tubería completa de firma y entrega.

A través de la 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" }
}
```

Los campos `event_type` y `payload` son opcionales; por defecto, son `webhook.test` y una carga útil de estado básica si se omiten.

## Notificaciones de señales de riesgo

Puede recibir notificaciones de webhook en tiempo real cada vez que se crea una señal de riesgo por cualquiera de las cinco rutas de detección del [Firewall de Identidad Antifraude](https://docs.truthlocks.com/es/guides/risk-signals.md) — ingesta directa, normalización de eventos, escaneo de deepfakes, detección de ATO y puntuación de velocidad.

Suscríbase a `risk.signal.*` para recibir todos los eventos de señales de riesgo, o suscríbase a `risk.signal.created` o `risk.signal.escalated` individualmente.

### Carga útil de ejemplo

```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"
  }
}
```

### Respuesta a señales de riesgo

Utilice webhooks de señales de riesgo para activar respuestas automatizadas —bloquear una sesión de usuario, notificar a su equipo de seguridad o escalar a un caso de fraude— sin sondear la 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]
>
> Los webhooks de señal de riesgo se activan para las señales creadas por las cinco rutas de detección. El campo `signal_source` en la carga útil le indica qué ruta generó la señal: `external`, `event_normalization`, `deepfake`, `ato` o `velocity`.

## Mejores prácticas

> [!TIP]
>
> Responda a los webhooks rápidamente. Realice su procesamiento pesado de forma asíncrona después de devolver una respuesta `200` para evitar tiempos de espera y reintentos.

* **Verifique cada firma.** Nunca omita la verificación de la firma, incluso en desarrollo.
* **Use una cola de mensajes.** Ponga en cola los eventos entrantes y procéselos en un trabajador para evitar bloquear la respuesta HTTP.
* **Manejar duplicados.** Use el encabezado `X-Truthlocks-Event-Id` para deduplicar eventos en caso de reintentos.
* **Monitorear fallos de entrega.** Revise la pestaña de entregas en la consola regularmente para detectar entregas fallidas o muertas.
* **Mantenga los secretos seguros.** Almacene su secreto de webhook en variables de entorno, no en el código fuente.


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