Una herramienta de automatización (Zapier, n8n, Make o Power Automate, y también Workato) suscribe su propia dirección a nuestros webhooks cuando arranca un flujo y cancela la suscripción cuando se detiene, sin que nadie copie una dirección en el portal. Usa una clave de API de la cuenta, en el plan Enterprise: webhooks:write suscribe y cancela suscripciones, webhooks:read lista las direcciones de la cuenta y lee los últimos avisos de cada evento (claves, permisos y errores). Ningún cliente de IA recibe nunca estos permisos. Los mensajes son los de webhooks: recibir y comprobar mensajes, firmados igual.
El permiso de lectura de cada evento
Además de webhooks:write o webhooks:read, la clave lleva el permiso de lectura de cada evento al que se suscribe o que lee: el permiso con el que nuestra API lee esas mismas filas. Sin él la llamada responde 403 con INSUFFICIENT_SCOPE, y details.scope dice qué permiso añadir.
| Permiso de lectura | Eventos |
|---|---|
releases:read |
release.published |
data:read |
gap.opened, gap.closed, price.changed, shelf.snapshot, summary.ready, ledger.updated |
issues:read |
issues.opened, issue.verified, issue.opened, issue.closed |
orders:read |
order.confirmed |
deliveries:read |
delivery.recorded |
campaigns:read |
campaign.response, promotion.result |
catalogue:read |
import.applied, import.ended |
Suscribir una dirección
POST /api/portal/v1/webhooks recibe url, events y, si quieres, format: standard (el nuestro, si no se pide otro), flat (un solo nivel de claves) o cloudevents. Las reglas son las del portal: https:// en el puerto estándar y un nombre público; nunca la dirección de una cadena, de una red de retail media o de un revendedor de datos; solo los eventos que tu cuenta tiene disponibles.
curl -X POST https://mercamap.com/api/portal/v1/webhooks \
-H "Authorization: Bearer mmk_…" -H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/in","events":["gap.opened"],"format":"flat"}'
La respuesta es un 201, con el id de la suscripción, su secreto de firma (whsec_…, que solo se muestra esta vez) y una cabecera Location: la dirección de su DELETE. La API guarda hasta 50 suscripciones por cuenta, aparte de las 5 direcciones creadas en el portal. Un rechazo es un 422 cuyo details.reason dice qué regla falló (destination, events, tooMany).
Listar y cancelar suscripciones
GET /api/portal/v1/webhooks lista cada dirección de la cuenta por su servidor, nunca su ruta ni su consulta, con createdBy (portal o api) y, en las de la API, keyId, la parte pública de la clave que la suscribió. DELETE /api/portal/v1/webhooks/{id} cancela una suscripción creada por la API, con sus mensajes en cola; vale cualquier clave de la cuenta con webhooks:write. Una dirección creada en el portal responde 403: quítala en el portal. La lista del portal nombra la clave de cada suscripción, y un administrador también la quita allí.
Una dirección añadida en el portal es del conector desde cuya página se añadió; una suscripción no es de ninguno, y en el portal aparece en la página principal de su formato («Webhook» para el nuestro, JSON plano y CloudEvents). Si un administrador la pausa allí, enabled vale false y no se le envía nada hasta que la reactive. Si el equipo de MercaMap desactiva una dirección de tu cuenta, la desactivación alcanza a las demás en el mismo servidor, también a las suscritas por la API (cláusula 12.4).
Cuando tu dirección responde 410
Un 410 significa «cancela la suscripción», como dice REST Hooks: borramos en el acto la suscripción creada por la API y no enviamos nada más a esa dirección. No se envía ningún correo, y la actividad de la cuenta lo registra. Una dirección creada en el portal se desactiva, como hasta ahora. Cualquier otra respuesta sigue los reintentos de la guía.
Cuando cambia una clave
Revocar una clave cancela todas las suscripciones que creó. Quitarle permisos cancela las que avisan de un evento que ya no lee. Antes de enviar nada volvemos a comprobar la clave: se borra la suscripción cuya clave está revocada, ha caducado o le falta el permiso de lectura de uno de sus eventos. Cada cancelación queda en la actividad de la cuenta.
Sondeo y muestras
GET /api/portal/v1/events/{type}?limit= lista los últimos avisos de un evento, del más reciente al más antiguo: 10 si no pides otra cifra, hasta 100. Cada aviso trae id, el event_id que llevan sus mensajes y el mismo en cada llamada (descarta los repetidos por él), y data con la forma del evento (referencia de webhooks). Se rehacen con lo que tu cuenta ve hoy: las semanas publicadas, los huecos abiertos ahora, los precios cambiados y las fotos de las últimas semanas publicadas, los últimos resultados de promociones, las incidencias abiertas y cerradas, los pedidos confirmados, los albaranes, las importaciones y sus trabajos. Los eventos cuyos momentos no se guardan no traen ninguno: issues.opened, issue.verified, gap.closed, campaign.response, summary.ready y ledger.updated. Un evento que tu cuenta no tiene disponible responde 403.
Power Automate y Swagger
Power Automate solo importa Swagger 2.0: /api/portal/v1/openapi.json?format=swagger2 da la misma descripción en ese formato. Su clave es una clave de API enviada en Authorization: escribe Bearer y un espacio delante. La suscripción figura como el disparador del conector, para que un flujo arranque con nuestros eventos.