La gestión de webhooks está disponible en /api/v2/webhooks. Trata las URL de webhook y el material de firma como secretos.
Antes de empezar
Crea una clave de API con el acceso mínimo del workspace y decide qué familia de eventos necesita tu integración.
Pasos
- Abre Settings → Integrations.
- Crea o selecciona un destino de webhook.
- Registra los ID de eventos configurados y el estado del endpoint.
- Envía una solicitud de prueba a un receptor que no sea de producción.
- Verifica la respuesta y revisa los intentos de entrega antes de activar el procesamiento de producción.
Mantén el receptor idempotente. Guarda el identificador del evento y confirma solo después de validar el payload. No supongas que todos los eventos internos de la aplicación son webhooks compatibles para clientes.
Configurar y verificar un webhook
- Crea un endpoint que acepte el payload y guarde el identificador del evento antes de devolver una respuesta correcta.
- En Settings → Integrations, crea un webhook con los campos visibles Name, Target hook URL, Event type y, si corresponde, Campaign o el valor de interés personalizado.
- Guárdalo, abre el destino y usa Test. Confirma que el receptor registra el evento y que la API informa
success: true. - Revisa Webhook events para consultar
status_code,success,retry_count,will_retryyerror_message. - Elimina o actualiza el destino cuando cambie su URL; eliminarlo no borra los intentos históricos.
Usa paginación por cursor (limit y starting_after) para el historial. Trata los reintentos como entregas al menos una vez y haz idempotente el consumidor.
Recuperación de errores
Una respuesta 4xx del receptor normalmente necesita corregir el payload o la autenticación; un 5xx o timeout puede reintentarse con backoff limitado. Confirma el siguiente intento en Webhook events y escala con el ID del evento y el estado redactado.
Referencia de campos
| Campo | Obligatorio | Significado |
|---|---|---|
| Name | Sí | Etiqueta del destino en el workspace. |
| Target hook URL | Sí | Endpoint HTTPS que acepta la entrega. |
| Event type | Sí | Identificador devuelto por el endpoint de tipos de evento. |
| Campaign | Opcional | Limita los eventos a una campaña cuando se selecciona. |
| Custom interest value | Condicional | Obligatorio cuando el evento seleccionado es una etiqueta de interés personalizada. |
Verificación de entrega
Después de Test, verifica que el receptor guardó el ID del evento, devolvió una respuesta correcta y no creó un duplicado al reintentar. En Webhook events, revisa status_code, success, retry_count, will_retry, error_message y timestamp_next_retry.