¿Qué es un webhook?
Un webhook te permite recibir una notificación cuando ocurren determinadas acciones del sistema mediante una llamada a una URL que tú proporcionas. Los webhooks también se conocen como “URL Callbacks” o “HTTP push calls”. Tu URL debe usar SSL y comenzar con HTTPS.Acciones de webhook
Consulta las acciones disponibles para webhooks.
Entendiendo los webhooks de Ayrshare
Los webhooks se categorizan por la acción específica y se registran a nivel del Primary Profile o del User Profile. Cualquier actualización para el Primary o el User Profile se envía primero al webhook registrado para el User Profile. Si el User Profile no tiene un webhook registrado, la actualización se enviará al webhook registrado en el Primary Profile. Por ejemplo:- Si un User Profile tiene un webhook Social Action registrado y desvincula TikTok, se llamará a la URL del webhook Social Action registrado para el User Profile. El webhook del Primary Profile no se llamará.
- Si un User Profile desvincula TikTok y no tiene un webhook Social Action registrado, pero el Primary Profile sí tiene un webhook registrado, se llamará a la URL del webhook Social Action registrado para el Primary Profile.
Registrar un webhook
Registra un webhook proporcionando una URL de endpoint y el tipo de acción al endpoint POST/hook/webhook. Cuando ocurra la acción, se enviará un mensaje HTTP POST a la URL proporcionada.
Por ejemplo, registra una URL para recibir notificaciones del estado de un scheduled post.
La URL de endpoint del webhook no debe usar redirecciones y debe ser la URL de destino final.
Si solo registras el webhook del Primary Profile, los User Profiles heredarán automáticamente el webhook del Primary Profile.
Para tener un webhook único para cada User Profile, debes registrar un webhook para cada User Profile.
Después de que tu webhook reciba el
HTTP POST, tu servidor debe responder
con un status HTTP 200 para marcar la llamada como correcta. Si tu servidor
no responde en 15 segundos, el intento se registra como fallido y se
reintenta. Responde en cuanto recibas la solicitud y realiza el procesamiento
de forma asíncrona: un timeout no es un rechazo, así que si tu handler
completa el trabajo pero responde tarde, el reintento hará que lo proceses dos
veces.Reintentos de webhook
Si la respuesta HTTP de tu servidor no está en el rango de éxito200-299, o tu servidor no responde en 15 segundos, el sistema reintentará automáticamente la llamada al webhook dos veces más. El primer reintento se realizará al cabo de 5 segundos y el segundo reintento 30 segundos después. Los reintentos tendrán el mismo hookId y el mismo payload.
Semántica de entrega e idempotencia
Ayrshare entrega los webhooks al menos una vez. Los duplicados ocasionales son parte del funcionamiento normal, no un defecto: todo consumidor necesita idempotencia como propiedad permanente. Los duplicados llegan en dos formas distintas, y cada una necesita una clave diferente:hookId identifica una entrega de un evento. Es idéntico en cada reintento de esa entrega, por lo que reclamar sobre él hace que los reintentos sean seguros. Pero una notificación nueva del mismo evento subyacente llega con un hookId nuevo, así que hookId por sí solo no reconocerá ese caso.
Patrón recomendado para el receptor:
- Responde primero. Devuelve
2xxinmediatamente y luego procesa de forma asíncrona. Un timeout no es un rechazo: si terminas el trabajo pero respondes tarde, el evento se vuelve a enviar. - Reclama
hookIdde forma atómica en el momento en que llega la solicitud: una restricción de unicidad, unINSERT ... ON CONFLICT DO NOTHINGo unSET NX, no una comprobación tipo lectura y luego escritura. Dos intentos pueden llegar de forma concurrente, y una comprobación seguida de una acción deja pasar a ambos. - Reclama también una clave propia, construida a partir del payload, para que una segunda notificación que traiga un
hookIdnuevo siga siendo reconocida. Enmessages,idcombinado consubActionfunciona bien. - Después haz el trabajo, manteniendo ambas reclamaciones el tiempo suficiente para cubrir la ventana de reintentos y cualquier renotificación posterior.
El
id del payload no es único por sí mismo para todos los tipos de evento:
el mismo id de mensaje se repite en ediciones y reacciones, y los payloads de
messageRead no llevan id, así que combínalo con subAction en lugar de
usarlo solo.Cabeceras de metadatos de entrega
Cada entrega lleva dos cabeceras que identifican esa transmisión concreta, para que puedas distinguir una original de un reintento:X-Ayrshare-Delivery-Attempt es 0 en el primer envío y se incrementa en uno con cada reintento, por lo que cualquier valor superior a 0 significa que ya hemos enviado esta entrega al menos una vez. Trátalo como un contador no acotado en lugar de un conjunto fijo de valores: el número de reintentos es un detalle operativo que puede cambiar. X-Ayrshare-Delivery-Id es único para cada intento; cítalo al contactar con soporte y sirve para identificar el registro exacto de la entrega.
Estas cabeceras identifican la transmisión; hookId identifica el evento. Deduplica por hookId, no por el delivery id: el delivery id es diferente en cada intento por diseño, así que nunca se reconocería nada como duplicado.
Seguridad de webhook
Puedes optar por añadir seguridad adicional configurando autenticación HMAC como solicitud HTTP. Esto se hace a menudo para prevenir ataques de repetición. Ayrshare utiliza HMAC-SHA256 para hashear el cuerpo del mensaje e incluye el hash y el UNIX timestamp en la cabecera del POST.X-Authorization-Content-SHA256 con el HMAC-SHA256 del cuerpo del POST. El signing secret es a nivel de perfil: un secret por User Profile, usado en todas las acciones de webhook de ese perfil, por lo que establecerlo para una acción lo cambia para todas las acciones de ese perfil. Las cuentas multiperfil gestionan un secret separado por perfil (apunta a un perfil con la cabecera Profile-Key).