¿Cómo recibo cada resultado con webhooks y compruebo que vienen de Talkyria?

Objetivo: Registrar webhooks por API, elegir sus eventos y verificar la firma de cada aviso.

Nivel: Avanzado · Duración: 3 min · Antes de esta lección: «¿Cómo recibo el resultado de cada llamada en mi sistema?»

Dónde, en Talkyria: app.talkyria.com/integraciones/api

Gancho

Un webhook sin verificar es una puerta abierta: cualquiera podría enviarle a tu sistema «pedido confirmado». La firma cierra esa puerta, y se comprueba con tres líneas de código.

Lo que vas a lograr

Vas a registrar un webhook por API, elegir sus eventos, leer el aviso y verificar su firma antes de creerle.

Pasos en pantalla

1. Registrar: POST https://api.talkyria.com/api/v1/webhooks con url, una dirección https pública, y events. Necesitas el permiso «Configurar el webhook saliente». Puedes tener hasta 10 por tienda.
2. Guarda el secret de la respuesta: empieza por whsec_ y no se vuelve a mostrar.
3. events por defecto es call.outcome_final, que recibe todos los resultados. Para recibir solo algunos, sepáralos por coma, por ejemplo call.confirmed,call.no_answer.
4. call.novelty_resolved y los eventos de llamadas con asesor no entran en el general: lístalos por su nombre o usa el asterisco.
5. Cada aviso trae event, siempre call.outcome_final por compatibilidad, y eventType con el evento exacto. La cabecera X-Talkyria-Event-Type también lo trae.
6. Verificar: calcula un HMAC SHA-256 del cuerpo tal como llegó, sin reformatearlo, con tu secreto. Compáralo con X-Talkyria-Signature, que llega como sha256= seguido del resultado en hexadecimal.
7. Si no coincide, descarta el aviso. Si coincide, responde rápido con un código 200 y procesa después.
8. Revisa entregas con GET /webhooks/{id}/deliveries, o en el panel, en «Integraciones» → «API» → «Webhooks» → «Entregas recientes».

Error común y cómo resolverlo

Calcular la firma sobre el JSON ya interpretado y vuelto a escribir. Un espacio o un orden distinto cambia la firma y todos tus avisos parecerán falsos. Firma el cuerpo crudo, exactamente como llegó.

¿Y ahora qué?

Ahora crea y edita tus Ofertas Inteligentes por API. Siguiente lección: «¿Puedo crear mis Ofertas Inteligentes por API?».