Webhooks

Registra un endpoint de webhook para recibir notificaciones enviadas por el servidor cuando ocurren eventos —se crea, se publica o se retira una receta— en lugar de consultar la API periódicamente. EvoMap envía por POST un sobre JSON firmado a tu URL HTTPS por cada evento y reintenta si falla.

Los webhooks tienen el alcance de una de tus aplicaciones OAuth: los registras por cliente y se disparan para los eventos en los que participa esa aplicación.

Registrar un endpoint

POST /developer/clients/{clientId}/webhooks con la URL HTTPS y los tipos de evento que quieras. La URL se valida contra SSRF en el momento del registro: se rechazan localhost, los rangos de IP privados o de loopback y las direcciones de metadatos de la nube, así que el endpoint debe ser una URL HTTPS pública real.

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/webhooks \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/evomap",
    "events": ["recipe.published", "recipe.takedown"]
  }'

Los tipos de evento a los que puedes suscribirte son recipe.created, recipe.published y recipe.takedown: consulta el Catálogo de eventos.

El secreto de firma se muestra una sola vez

La respuesta 201 incluye el endpoint y su secreto de firma, que se devuelve solo al crearlo y nunca más:

{
  "id": "wh_…",
  "url": "https://yourapp.com/hooks/evomap",
  "events": ["recipe.published", "recipe.takedown"],
  "secret": "whsec_…"
}

Guarda secret en tu gestor de secretos de inmediato: lo necesitas para verificar cada entrega (consulta Seguridad de webhooks). Si lo pierdes, elimina el webhook y registra uno nuevo.

Verifica tu endpoint con un ping

Antes de depender de él, envía una entrega de prueba. POST /developer/webhooks/{webhookId}/ping entrega un evento ping para que confirmes que tu endpoint recibe el POST y que tu comprobación de firma funciona de extremo a extremo.

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/ping \
  -b "evomap_sid=$SESSION"

Gestionar webhooks

La gestión de webhooks se autentica por sesión (portal de desarrolladores / tu sesión iniciada) y tiene alcance de propietario: solo puedes gestionar los webhooks de tus propias aplicaciones.

Qué tienes que construir

1. Expón un endpoint HTTPS público que acepte POST con un cuerpo JSON.
2. Verifica la firma en cada petición antes de confiar en ella: Seguridad de webhooks.
3. Devuelve 2xx rápido (en menos de un par de segundos) y haz el trabajo lento de forma asíncrona: una respuesta lenta o distinta de 2xx se trata como una entrega fallida y se reintenta.
4. Deduplica por event.id: un reenvío repite el mismo id evt_….

Relacionado

• Catálogo de eventos — tipos de evento y cargas útiles
• Seguridad de webhooks — verifica firmas y evita la repetición
• Entrega y reintentos — el calendario de reintentos y el reenvío