Webhooks

Un webhook es una llamada HTTP que Sofia lanza cuando una publicación está en línea o falla. Úsalo para recuperar el contenido en una hoja de cálculo, avisar a una herramienta de mensajería o lanzar un escenario en Zapier o n8n.

Añadir uno

• 1. Dale una dirección. Una dirección https pública a la que Sofia enviará el evento.
• 2. Elige los eventos. post.published y post.failed.
• 3. Regístralo. POST /v1/webhooks: el secreto de firma (whsec_…) solo se muestra en esa respuesta.
• 4. Envía una prueba. POST /v1/webhooks/{id}/test envía un evento webhook.test, firmado como los demás.

La solicitud completa se detalla en la pestaña API: Registrar un webhook. Solo se anuncian las publicaciones creadas por tu aplicación.

Construir el receptor

Envía siempre una prueba primero y conserva el cuerpo recibido: es el contrato, más fiable que cualquier descripción. Sofia envía cada evento por POST en formato JSON { id, type, createdAt, data }, con las cabeceras Sofia-Event-Id, Sofia-Event-Type y Sofia-Signature.

• Verifica la firma. Sofia-Signature vale t=<unix time>,v1=<hex>, donde v1 es el HMAC-SHA256 de <t>.<raw body> con tu secreto. Calcúlalo sobre el cuerpo sin procesar y rechaza una marca de tiempo antigua.
• Responde `2xx` rápido, y haz el trabajo después: un punto de llegada lento no se distingue de uno caído.
• Sé idempotente. Un mismo evento puede llegar dos veces: deduplica por Sofia-Event-Id.

Cuando un webhook deja de dispararse

La dirección no es accesible

Sofia llama desde sus servidores: la dirección debe ser un https público. Nunca se sigue una redirección, y 10 segundos sin respuesta cuentan como un fallo.

La dirección devuelve un error

Cualquier respuesta distinta de 2xx provoca un nuevo intento tras 1 minuto, 5 minutos, 30 minutos y 2 horas, hasta 5 intentos. Mira primero tus propios registros y luego reproduce con POST /v1/webhooks/{id}/test.

La publicación no fue creada por tu aplicación

Un webhook solo anuncia las publicaciones creadas por tu aplicación; una publicación creada en la interfaz no lo dispara.

Lee también

Un webhook dice cuándo ha actuado Sofia. Para hacer que Sofia actúe, usa Sofia API, la CLI sofia o el servidor MCP (pestañas API y Agents), o Integraciones de terceros.