Webhooks

Cuando ocurre un evento en alguna cuenta comitente — ejemplo: se crea una orden, cambia el estado de una solicitud, se acredita un depósito— le enviamos una llamada HTTP a la dirección que configuremos para notificarlos sobre dicho evento.

Pasos para integrarte

1. Publicá un endpoint HTTPS
   Una URL pública que acepte POST con cuerpo JSON y responda 200.
   Los requisitos completos están más abajo.
2. Elegí cómo querés que nos autentiquemos
   Bearer token, Basic o headers propios. Las credenciales se pasan por canal seguro y quedan guardadas cifradas.
3. Elegí los eventos que querés recibir
   De la lista de eventos disponibles. La suscripción es explícita: solo llega lo que se pide.
4. Registramos la configuración
   Nos deben compartir la url para recibir los webhook, el mecanismo de autenticación elegido y las credenciales.
   
   Desde API Broker, damos de alta la URL con la autenticación y los eventos elegidos.
   
   Devolvemos un client_hook_id, que es el identificador con el que después el cliente puede consultar y modificar su configuración por sí mismo.
5. Probamos en el ambiente de desarrollo — en conjunto
   Generamos una operación de prueba y el cliente verifica de su lado que llegó el POST, que la autenticación validó y que su servicio respondió 200. Este paso es el que detecta problemas de ruteo antes de que lleguen a producción.
6. Habilitamos producción — en conjunto
   Repetimos el alta en el ambiente productivo y hacemos una verificación final con una operación controlada.

Requisitos del endpoint

Como es el body del webhook

El body del mensaje siempre tiene dos claves:

• topic — identifica el evento. Es el valor de la tabla de eventos disponibles.
• items — array con la entidad afectada.

El objeto dentro de items es el mismo que devuelve la API REST para ese recurso. La representación de una orden en la notificación es idéntica a la que se obtiene consultando la orden por la API, así que no hay un formato paralelo que mantener.

POST /tu/path/de/webhook HTTP/1.1
Host: tu-dominio
Content-Type: application/json
Authorization: Bearer <el token acordado>

{
  "topic": "market_order_update",
  "items": [
    {
      "market_order_id": 1048576,
      "status": "EXECUTED"
    }
  ]
}

El resto de los campos del recurso vienen igual que en la API REST.

Eventos disponibles

La columna Identificador es el campo que identifica unívocamente la entidad dentro de items: sirve para relacionar la notificación con los registros propios del cliente.

La lista habilitada en cada ambiente, con el topic_id que se usa para suscribirse, se consulta en GET /api/notifications/topics.

Autenticación

El partner elige un esquema de autenticación
Vamos a mandar esas credenciales en cada llamada para que pueda verificar que la notificación viene de nosotros.

Consultar y modificar la configuración

Con el token habitual de la API (Authorization: Bearer). Base: /api/notifications.