Ganchos web

Los webhooks envían un POST HTTPS a tu servidor cada vez que ocurre algo en Serpfull. Adminístralos en Integraciones → Webhooks (propietarios y administradores). Para el formato de carga útil, encabezados y código de verificación, consulta la referencia de la API de Webhooks.

Verificando firmas

• Abre Integraciones → Webhooks y presiona Añadir endpoint.
• Introduce una URL https pública en el puerto 443. Se rechazan direcciones privadas, internas, loopback, link-local y de metadatos en la nube (verificamos cada dirección a la que resuelve el host, al guardar y en cada entrega), y no se siguen redirecciones.
• Añade una descripción opcional, elige los sitios web que cubre (todos los sitios, incluidos los futuros, o algunos seleccionados) y marca los eventos a enviar.
• Copia el secreto de firma que aparece después de guardar. Puedes revelarlo de nuevo desde la tarjeta del endpoint o rotarlo.

Reintentos

Responda con cualquier 2xx en 10 segundos. Cualquier otra cosa, o un tiempo de espera, se vuelve a intentar después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas y 24 horas; Después de 8 intentos, la entrega se marca como fallida. Responder 410 Ha ido para detener los reintentos de ese evento. Configuración → Webhooks muestra entregas recientes, le permite volver a intentar una fallida y enviar un test.ping.

Idempotencia

Las entregas son al menos una vez. Cada solicitud lleva Serpfull-Event-Id (también el campo de identificación en el cuerpo); guárdelo e ignore las repeticiones. Serpfull-Delivery-Attempt le indica cuál es el intento.

Reglas de punto final

Los puntos finales deben ser URL HTTPS públicas en el puerto 443. Se rechazan las direcciones privadas, de bucle invertido y de enlace local, y no se siguen las redirecciones.

Reintentos y desactivación

Responda con cualquier 2xx en 10 segundos. De lo contrario, reintentamos después de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas y 24 horas (8 intentos, aproximadamente 45 horas). Responda 410 Gone para dejar de reintentar ese evento. Si un endpoint sigue fallando durante 3 días (y al menos 10 intentos seguidos), lo desactivamos, eliminamos sus eventos en cola y notificamos a su equipo en la aplicación. La integración de Webhooks entonces muestra Necesita atención. Arregle el receptor y vuelva a activar el endpoint.

Rotando el secreto

Rotar el secreto le proporciona un nuevo secreto de inmediato. Durante las próximas 24 horas, cada solicitud se firma con el secreto nuevo y el antiguo (dos valores v1), para que pueda actualizar su receptor sin perder eventos.

De un asistente

El conector de IA tiene webhooks_list_endpoints, webhooks_create_endpoint, webhooks_update_endpoint, webhooks_delete_endpoint, webhooks_send_test, webhooks_list_deliveries y webhooks_redeliver. Los secretos solo se muestran en el panel.