# Webhooks

Utilice Webhooks para recibir eventos de tareas y facturación sin sondeo. Tripo envía cargas útiles de JSON a su punto final HTTPS cuando ocurren eventos de suscripción.

## Configuración

1. Abra Configuración, luego Webhooks.
2. Agregue un punto final HTTPS, como `https://api.yourapp.com/tripo-webhook`.
3. Seleccione los tipos de eventos que desea recibir.
4. Guarde el punto final.
5. Copie el secreto de firma y guárdelo de forma segura. Se muestra sólo una vez.

## Tipos de eventos

| Evento | Descripción |
| --- | --- |
| `task.completed` | Una tarea finalizó exitosamente. |
| `task.failed` | Una tarea falló o fue cancelada. |
| `balance.low` | El saldo de la cuenta cayó por debajo del umbral de alerta de crédito configurado. |

## Encabezados de solicitud

| encabezado | Descripción |
| --- | --- |
| `Tripo-Webhook-Id` | Punto final Webhook ID. |
| `Tripo-Webhook-Delivery` | Entrega única ID. Úselo para la idempotencia. |
| `Tripo-Webhook-Event` | Tipo de evento, como `task.completed`. |
| `Tripo-Webhook-Signature` | Firma HMAC-SHA256 sobre `{timestamp}.{raw_body}`. |
| `Content-Type` | Siempre `application/json`. |

## Verificación

1. Analice `t` y `v1` de `Tripo-Webhook-Signature`.
2. Calcule HMAC-SHA256 con el secreto de firma sobre `t + "." + rawBody`.
3. Compare el resumen hexadecimal calculado con `v1` mediante una comparación de tiempo constante.
4. Opcionalmente, rechace las marcas de tiempo de más de cinco minutos.

## Mejores prácticas

- Devuelva una respuesta `2xx` rápidamente y luego procese el trabajo pesado de forma asincrónica.
- Verifique cada carga útil antes de cambiar el estado de la aplicación.
- Deduplicar eventos usando `Tripo-Webhook-Delivery`.
- Utilice `balance.low` para alertar a los usuarios antes de que falle la creación de tareas debido a créditos insuficientes.