Webhooks de cobros
Registra una URL HTTPS de tu comercio y Migo le envía un POST firmado cada vez que un cobro con terminal de ese comercio se aprueba o se rechaza. Te sirve para conciliar en tu ERP o en tu backend sin consultar el historial.
Un webhook se registra por comercio y recibe los cobros de todas sus sucursales y terminales, tanto con tarjeta presente como con pagos alternativos.
Eventos
| Evento | Cuándo se envía |
|---|---|
terminal.payment.approved | El cobro quedó aprobado. |
terminal.payment.denied | El cobro se rechazó antes de aprobarse (estaba creado). Un cobro que ya se notificó como aprobado nunca genera un rechazo. |
Cada webhook recibe solo los eventos que lista en events.
- Las cancelaciones y las reversiones no emiten ningún evento, tampoco la reversión de un cobro autorizado.
- Un cobro que ya se notificó como aprobado puede cambiar después (por ejemplo, cancelarse o reversarse) sin que llegue otro evento. Si tu conciliación depende del estado final, contrástalo con el historial de transacciones.
Administrar los webhooks
Las cinco rutas viven en el Wallet Gateway (https://api.ali.app/rest en producción, https://ali-qa.ali.app/rest en QA), bajo /rest/businesses/commerces/{commerceId}/webhooks.
| Método y ruta | Qué hace | Respuesta |
|---|---|---|
POST /rest/businesses/commerces/{commerceId}/webhooks | Registra un webhook | 201 con el webhook y su secret |
GET /rest/businesses/commerces/{commerceId}/webhooks | Lista los webhooks del comercio, del más nuevo al más viejo | 200 |
GET /rest/businesses/commerces/{commerceId}/webhooks/{webhookId} | Obtiene un webhook | 200 |
PATCH /rest/businesses/commerces/{commerceId}/webhooks/{webhookId} | Edita, pausa o reactiva un webhook | 200 |
DELETE /rest/businesses/commerces/{commerceId}/webhooks/{webhookId} | Elimina un webhook | 200 con { "id": "..." } |
El detalle de cada esquema está en la referencia interactiva del Wallet Gateway.
Autenticación y permisos
| Header | Valor |
|---|---|
Authorization | Bearer <JWT de tu aplicación> |
x-user-token | Token del usuario dueño del comercio |
- La aplicación necesita el permiso
businesses:createBusiness, y el usuario dueño también. - Solo el dueño del comercio puede administrar sus webhooks. Otro usuario vinculado al comercio recibe
404. - Las aplicaciones con rol ADMIN o SUPPORT pueden omitir
x-user-tokeny administrar cualquier comercio.
Registrar un webhook
curl -X POST "https://ali-qa.ali.app/rest/businesses/commerces/335/webhooks" \
-H "Authorization: Bearer $APP_JWT" \
-H "x-user-token: $OWNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://erp.example.com/hooks/migo",
"events": ["terminal.payment.approved", "terminal.payment.denied"],
"headers": [{ "name": "X-Api-Key", "value": "my-integration-key" }]
}'
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
url | string | Sí | URL HTTPS pública que recibe los eventos. Máximo 2048 caracteres. Ver Reglas de la URL. |
events | string[] | Sí | Al menos uno de terminal.payment.approved y terminal.payment.denied. |
headers | object[] | No | Hasta 5 headers { name, value } que se envían en cada entrega. Ver Headers personalizados. |
{
"success": true,
"data": {
"id": "65f1c2a9e4b0a1b2c3d4e5f6",
"commerceId": 335,
"url": "https://erp.example.com/hooks/migo",
"events": ["terminal.payment.approved", "terminal.payment.denied"],
"enabled": true,
"headers": [{ "name": "X-Api-Key", "value": "****-key" }],
"createdAt": "2026-10-01T15:04:05.000Z",
"updatedAt": "2026-10-01T15:04:05.000Z",
"secret": "whsec_<your-secret>"
}
}
secret solo aparece en esta respuesta. Ninguna lectura posterior lo devuelve y no se puede consultar ni regenerar. Si lo pierdes, elimina el webhook y regístralo de nuevo: el nuevo registro trae un secreto nuevo.
Listar y consultar
GET devuelve el mismo objeto sin secret, con los valores sensibles enmascarados:
- El
valuede cada header llega como****seguido de sus últimos 4 caracteres (solo****si tiene 4 caracteres o menos). - Los valores de la query string de la
urlllegan como****; los nombres de los parámetros se conservan. Por ejemplo,https://erp.example.com/hooks/migo?token=abc123se lee comohttps://erp.example.com/hooks/migo?token=****.
Editar, pausar o reactivar
PATCH cambia solo los campos que envías:
| Campo | Tipo | Descripción |
|---|---|---|
url | string | Nueva URL. Se valida de nuevo con las mismas reglas. |
events | string[] | Reemplaza la lista de eventos (al menos uno). |
enabled | boolean | false pausa el webhook y true lo reactiva. |
headers | object[] | Reemplaza toda la lista. [] elimina todos los headers. |
curl -X PATCH "https://ali-qa.ali.app/rest/businesses/commerces/335/webhooks/65f1c2a9e4b0a1b2c3d4e5f6" \
-H "Authorization: Bearer $APP_JWT" \
-H "x-user-token: $OWNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'
El secreto nunca cambia con un PATCH: pausar y reactivar conserva el mismo secreto.
Mientras está pausado, el webhook no recibe eventos nuevos. Las entregas que ya estaban en cola siguen su calendario de reintentos; para descartarlas, elimina el webhook.
Eliminar
DELETE borra el webhook; sus entregas pendientes ya no se envían (una que esté saliendo en ese instante puede llegar igual). La respuesta trae solo el id:
{ "success": true, "data": { "id": "65f1c2a9e4b0a1b2c3d4e5f6" } }
Límites
- Hasta 5 webhooks por comercio.
- La
urles única dentro del comercio: no puedes registrar dos webhooks con la misma URL.
Reglas de la URL
La URL se valida al registrarla y cada vez que la cambias. Tiene que:
- usar
https; - usar el puerto 443 (sin puerto en la URL, o
:443); - no llevar usuario ni contraseña;
- tener un nombre de host público (un dominio), nunca una IP literal;
- resolver solo a direcciones IP públicas: si alguna de las direcciones del dominio es privada, local, reservada o de documentación, se rechaza.
La resolución se repite en cada entrega. Si en ese momento el dominio apunta a una dirección no pública, esa entrega se descarta sin reintentos.
Headers personalizados
Puedes agregar hasta 5 headers para que tu endpoint autentique la llamada (por ejemplo, una API key propia):
- Nombre: de 1 a 64 caracteres, solo letras, dígitos y
-. No se puede repetir en la lista (sin distinguir mayúsculas). - Valor: hasta 512 caracteres ASCII imprimibles o tabulador. No admite saltos de línea ni caracteres fuera de ASCII.
- Nombres reservados (sin distinguir mayúsculas):
Host,Content-Length,Content-Type,Transfer-Encoding,Connection,Content-Encoding,Expect,Upgrade,TE,Trailer,Keep-Alive,Forwarded, y cualquiera que empiece conX-Migo-,Proxy-oX-Forwarded-.
Los valores se guardan cifrados y solo se devuelven enmascarados.
Errores
Los errores usan el envelope de siempre, { "success": false, "errors": [{ "code", "message" }] }:
| HTTP | Código | Cuándo |
|---|---|---|
400 | 7000 | El body no tiene la forma esperada: falta url o events, events está vacío o trae un evento desconocido, url supera 2048 caracteres, enabled no es booleano. |
400 | 7715 | La URL no cumple las reglas de la URL. |
400 | 7716 | Los headers no cumplen las reglas de los headers o son más de 5. |
401 | — | Falta o es inválido el JWT de la aplicación, o falta x-user-token en una aplicación que no es ADMIN ni SUPPORT. |
403 | — | La aplicación o el usuario no tienen el permiso businesses:createBusiness, o una aplicación que no es ADMIN ni SUPPORT llama sin usuario. |
404 | 7408 | El usuario no es dueño del comercio, o el comercio no existe. |
404 | 7713 | El webhook no existe en ese comercio. |
409 | 7714 | El comercio ya tiene 5 webhooks (solo en POST). |
409 | 7717 | El comercio ya tiene un webhook con esa URL. |
Con varios problemas a la vez, el POST informa uno solo, en este orden: headers (7716), URL (7715), límite (7714) y URL duplicada (7717).
La entrega
Cada evento llega como un POST a tu URL con estos headers:
| Header | Valor |
|---|---|
Content-Type | application/json |
User-Agent | Migo-Webhooks/1.0, salvo que registres tu propio User-Agent como header personalizado |
X-Migo-Event | Tipo de evento, por ejemplo terminal.payment.approved |
X-Migo-Event-Id | Identificador del evento, igual al id del body |
X-Migo-Timestamp | Momento del envío, en segundos Unix |
X-Migo-Signature | t=<unix>,v1=<hex>; ver Verificar la firma |
Además llegan los headers personalizados que registraste.
El body
{
"id": "evt_9c1f0b7a2e4d6f8a1b3c5d7e",
"type": "terminal.payment.approved",
"apiVersion": "2026-10-01",
"createdAt": "2026-10-01T15:04:05.120Z",
"data": {
"terminalPaymentId": 105453,
"operationId": "OP-20261001-000123",
"status": "approved",
"authorizationCode": "186653",
"paymentMethodType": "card",
"amount": { "subtotal": "125.5", "currency": "GTQ" },
"commerce": { "id": 335 },
"branch": { "id": 341 },
"terminal": { "id": 441, "externalId": "138438", "deviceId": "SMOPY0000EXAMPLE" },
"card": { "bin": "529999", "last4": "1113", "brand": "MASTERCARD" },
"occurredAt": "2026-10-01T15:04:05.120Z",
"paymentCreatedAt": "2026-10-01T15:03:50.000Z"
}
}
{
"id": "evt_4b2d8e6f1a3c5e7a9b0d2f4a",
"type": "terminal.payment.denied",
"apiVersion": "2026-10-01",
"createdAt": "2026-10-01T15:10:41.310Z",
"data": {
"terminalPaymentId": 105460,
"operationId": "OP-20261001-000131",
"status": "denied",
"authorizationCode": null,
"paymentMethodType": "card",
"amount": { "subtotal": "3.35", "currency": "GTQ" },
"commerce": { "id": 335 },
"branch": { "id": 341 },
"terminal": { "id": 441, "externalId": "138438", "deviceId": "SMOPY0000EXAMPLE" },
"card": { "bin": "529999", "last4": "1113", "brand": "MASTERCARD" },
"decline": { "code": "05", "reason": "No autorizada" },
"occurredAt": "2026-10-01T15:10:41.310Z",
"paymentCreatedAt": "2026-10-01T15:10:30.000Z"
}
}
Envelope
| Campo | Tipo | Descripción |
|---|---|---|
id | string | Identificador del evento (evt_ + 24 caracteres hexadecimales). Es estable: el mismo cobro y el mismo tipo de evento siempre producen el mismo id, también en los reintentos. |
type | string | terminal.payment.approved o terminal.payment.denied. |
apiVersion | string | Versión del formato del evento: 2026-10-01. |
createdAt | string | Momento en que se generó el evento (ISO 8601, UTC). |
data | object | Los datos del cobro. |
data
| Campo | Tipo | Descripción |
|---|---|---|
terminalPaymentId | number | Identificador del cobro con terminal. |
operationId | string | null | Identificador de la operación, si existe. |
status | string | approved o denied. |
authorizationCode | string | null | Código de autorización. Puede ser null, sobre todo en rechazos y en pagos alternativos. |
paymentMethodType | string | card para tarjeta presente; en pagos alternativos, el identificador del método. |
amount.subtotal | string | Monto bruto cobrado a la tarjeta, como string decimal sin cantidad fija de decimales ("2", "125.5", "3.35"). Conviértelo con un tipo decimal, no con punto flotante. |
amount.total | string | Opcional. Monto neto después de comisiones, mismo formato que subtotal. Solo viaja cuando el cobro ya se liquidó; los eventos approved y denied se emiten antes de liquidar, así que hoy normalmente no viene. Nunca se envía "0". subtotal no es el monto que recibe el comercio: no lo acredites como neto. |
amount.currency | string | Código de moneda ISO 4217 alfabético. |
commerce.id | number | Comercio del cobro. |
branch.id | number | Sucursal del cobro. |
terminal.id | number | Terminal del cobro. |
terminal.externalId | string | null | Identificador externo de la terminal. |
terminal.deviceId | string | null | Identificador del dispositivo. |
card | object | null | Solo bin (primeros 6 dígitos), last4 y brand; cualquiera de los tres puede ser null. Es null en pagos alternativos o si no hay datos de tarjeta. Nunca se envía el número completo, el titular ni otros datos de la tarjeta. |
decline | object | Solo en terminal.payment.denied. code (hasta 4 caracteres alfanuméricos) y reason (hasta 120 caracteres); cualquiera puede ser null. |
occurredAt | string | Momento en que se emitió el evento (ISO 8601, UTC). |
paymentCreatedAt | string | null | Momento en que se inició el cobro (ISO 8601, UTC). |
Verificar la firma
Cada entrega se firma con el secret del webhook. El header tiene la forma:
X-Migo-Signature: t=1790867045,v1=5f2b0c...e91a
Para verificarlo:
- Toma el body crudo, exactamente los bytes recibidos, antes de parsear el JSON. Si lo parseas y lo vuelves a serializar, la firma no coincide.
- Separa
tyv1del header. - Calcula
HMAC-SHA256(secret, t + "." + body)en hexadecimal. La clave es elsecretcompleto, incluido el prefijowhsec_. - Compara el resultado con
v1en tiempo constante. - Rechaza el evento si
|ahora − t|es mayor a 300 segundos. Cada intento se firma de nuevo con su propiot, así que los reintentos también pasan esta verificación. - Deduplica por
idantes de procesar (ver Garantías de entrega).
Si la verificación falla, responde 400 y no proceses el evento.
Node.js
const crypto = require('node:crypto');
const express = require('express');
const SECRET = process.env.MIGO_WEBHOOK_SECRET; // whsec_<your-secret>
const TOLERANCE_SECONDS = 300;
function verifyMigoSignature(rawBody, header, secret) {
const parts = Object.fromEntries(
(header || '').split(',').map((part) => part.split('=', 2)),
);
const timestamp = Number(parts.t);
if (!Number.isInteger(timestamp) || !parts.v1) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
const received = Buffer.from(parts.v1, 'utf8');
const computed = Buffer.from(expected, 'utf8');
return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}
const app = express();
app.post('/hooks/migo', express.raw({ type: 'application/json' }), async (req, res) => {
const rawBody = req.body.toString('utf8');
if (!verifyMigoSignature(rawBody, req.get('X-Migo-Signature'), SECRET)) {
return res.status(400).end();
}
const event = JSON.parse(rawBody);
if (await alreadyProcessed(event.id)) return res.status(200).end();
await enqueueForProcessing(event); // procesa fuera de la respuesta
res.status(200).end();
});
Python
import hashlib
import hmac
import json
import os
import time
from flask import Flask, request
SECRET = os.environ["MIGO_WEBHOOK_SECRET"] # whsec_<your-secret>
TOLERANCE_SECONDS = 300
def verify_migo_signature(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(part.split("=", 1) for part in (header or "").split(",") if "=" in part)
try:
timestamp = int(parts["t"])
received = parts["v1"]
except (KeyError, ValueError):
return False
if abs(int(time.time()) - timestamp) > TOLERANCE_SECONDS:
return False
signed = f"{timestamp}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received)
app = Flask(__name__)
@app.post("/hooks/migo")
def migo_webhook():
raw_body = request.get_data()
if not verify_migo_signature(raw_body, request.headers.get("X-Migo-Signature"), SECRET):
return "", 400
event = json.loads(raw_body)
if already_processed(event["id"]):
return "", 200
enqueue_for_processing(event) # procesa fuera de la respuesta
return "", 200
Reintentos
Una entrega es exitosa cuando tu endpoint responde con un status 2xx en menos de 10 segundos.
- No se siguen redirecciones: un
3xxcuenta como fallo. - El body de tu respuesta se ignora.
- Cualquier otro status (incluidos
4xxcomo400,403,404,413o429), un timeout o un error de conexión cuentan como fallo y se reintentan con el calendario de abajo. Cada reintento se firma de nuevo.Retry-Afterno se tiene en cuenta.
Después del primer intento, que sale apenas se aprueba o rechaza el cobro, los reintentos esperan:
| Reintento | Espera desde el intento anterior |
|---|---|
| 1 | 5 minutos |
| 2 | 15 minutos |
| 3 | 30 minutos |
| 4 | 2 horas |
| 5 | 6 horas |
| 6 | 24 horas |
Cada espera puede alargarse hasta unos 5 minutos más. Son 7 intentos en total, a lo largo de unas 33 horas; si ninguno tiene éxito, el evento se descarta y no se vuelve a enviar. Estos valores (y el límite de webhooks por comercio y el timeout) son los de la configuración actual de Migo; si cambian, se anuncia en el changelog.
Garantías de entrega
- Al menos una vez: el mismo evento puede llegar más de una vez, por ejemplo si tu endpoint lo procesó pero respondió tarde. Deduplica siempre por
id(o por el headerX-Migo-Event-Id, que tiene el mismo valor). - Sin orden garantizado: los eventos pueden llegar en un orden distinto al de los cobros, sobre todo cuando hay reintentos. Usa
occurredAtypaymentCreatedAtpara ordenarlos. - Responde rápido: confirma con
2xxen cuanto verifiques la firma y procesa el evento después. Si tu lógica tarda más de 10 segundos, el intento cuenta como fallo y se reenvía. - El cobro no depende del webhook: un endpoint caído o lento no afecta el cobro ni su respuesta en la terminal.
Relacionado
- Flujo de transacción — cómo se aprueba o rechaza un cobro en la terminal.
- Reversar un cobro autorizado — la reversión no genera evento.
- Catálogo de errores — todos los códigos de error.