Saltar al contenido principal
Migo Docs

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​

EventoCuándo se envía
terminal.payment.approvedEl cobro quedó aprobado.
terminal.payment.deniedEl 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.

Lo que no genera evento
  • 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 rutaQué haceRespuesta
POST /rest/businesses/commerces/{commerceId}/webhooksRegistra un webhook201 con el webhook y su secret
GET /rest/businesses/commerces/{commerceId}/webhooksLista los webhooks del comercio, del más nuevo al más viejo200
GET /rest/businesses/commerces/{commerceId}/webhooks/{webhookId}Obtiene un webhook200
PATCH /rest/businesses/commerces/{commerceId}/webhooks/{webhookId}Edita, pausa o reactiva un webhook200
DELETE /rest/businesses/commerces/{commerceId}/webhooks/{webhookId}Elimina un webhook200 con { "id": "..." }

El detalle de cada esquema está en la referencia interactiva del Wallet Gateway.

Autenticación y permisos​

HeaderValor
AuthorizationBearer <JWT de tu aplicación>
x-user-tokenToken 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-token y 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" }]
}'
CampoTipoRequeridoDescripción
urlstringSíURL HTTPS pública que recibe los eventos. Máximo 2048 caracteres. Ver Reglas de la URL.
eventsstring[]SíAl menos uno de terminal.payment.approved y terminal.payment.denied.
headersobject[]NoHasta 5 headers { name, value } que se envían en cada entrega. Ver Headers personalizados.
201 Created
{
"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>"
}
}
Guarda el secreto ahora

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 value de 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 url llegan como ****; los nombres de los parámetros se conservan. Por ejemplo, https://erp.example.com/hooks/migo?token=abc123 se lee como https://erp.example.com/hooks/migo?token=****.

Editar, pausar o reactivar​

PATCH cambia solo los campos que envías:

CampoTipoDescripción
urlstringNueva URL. Se valida de nuevo con las mismas reglas.
eventsstring[]Reemplaza la lista de eventos (al menos uno).
enabledbooleanfalse pausa el webhook y true lo reactiva.
headersobject[]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:

200 OK
{ "success": true, "data": { "id": "65f1c2a9e4b0a1b2c3d4e5f6" } }

Límites​

  • Hasta 5 webhooks por comercio.
  • La url es ú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 con X-Migo-, Proxy- o X-Forwarded-.

Los valores se guardan cifrados y solo se devuelven enmascarados.

Errores​

Los errores usan el envelope de siempre, { "success": false, "errors": [{ "code", "message" }] }:

HTTPCódigoCuándo
4007000El 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.
4007715La URL no cumple las reglas de la URL.
4007716Los 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.
4047408El usuario no es dueño del comercio, o el comercio no existe.
4047713El webhook no existe en ese comercio.
4097714El comercio ya tiene 5 webhooks (solo en POST).
4097717El 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:

HeaderValor
Content-Typeapplication/json
User-AgentMigo-Webhooks/1.0, salvo que registres tu propio User-Agent como header personalizado
X-Migo-EventTipo de evento, por ejemplo terminal.payment.approved
X-Migo-Event-IdIdentificador del evento, igual al id del body
X-Migo-TimestampMomento del envío, en segundos Unix
X-Migo-Signaturet=<unix>,v1=<hex>; ver Verificar la firma

Además llegan los headers personalizados que registraste.

El body​

terminal.payment.approved
{
"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"
}
}
terminal.payment.denied
{
"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

CampoTipoDescripción
idstringIdentificador 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.
typestringterminal.payment.approved o terminal.payment.denied.
apiVersionstringVersión del formato del evento: 2026-10-01.
createdAtstringMomento en que se generó el evento (ISO 8601, UTC).
dataobjectLos datos del cobro.

data

CampoTipoDescripción
terminalPaymentIdnumberIdentificador del cobro con terminal.
operationIdstring | nullIdentificador de la operación, si existe.
statusstringapproved o denied.
authorizationCodestring | nullCódigo de autorización. Puede ser null, sobre todo en rechazos y en pagos alternativos.
paymentMethodTypestringcard para tarjeta presente; en pagos alternativos, el identificador del método.
amount.subtotalstringMonto 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.totalstringOpcional. 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.currencystringCódigo de moneda ISO 4217 alfabético.
commerce.idnumberComercio del cobro.
branch.idnumberSucursal del cobro.
terminal.idnumberTerminal del cobro.
terminal.externalIdstring | nullIdentificador externo de la terminal.
terminal.deviceIdstring | nullIdentificador del dispositivo.
cardobject | nullSolo 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.
declineobjectSolo en terminal.payment.denied. code (hasta 4 caracteres alfanuméricos) y reason (hasta 120 caracteres); cualquiera puede ser null.
occurredAtstringMomento en que se emitió el evento (ISO 8601, UTC).
paymentCreatedAtstring | nullMomento 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:

  1. 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.
  2. Separa t y v1 del header.
  3. Calcula HMAC-SHA256(secret, t + "." + body) en hexadecimal. La clave es el secret completo, incluido el prefijo whsec_.
  4. Compara el resultado con v1 en tiempo constante.
  5. Rechaza el evento si |ahora − t| es mayor a 300 segundos. Cada intento se firma de nuevo con su propio t, así que los reintentos también pasan esta verificación.
  6. Deduplica por id antes de procesar (ver Garantías de entrega).

Si la verificación falla, responde 400 y no proceses el evento.

Node.js​

verify-migo-webhook.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​

verify_migo_webhook.py
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 3xx cuenta como fallo.
  • El body de tu respuesta se ignora.
  • Cualquier otro status (incluidos 4xx como 400, 403, 404, 413 o 429), 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-After no se tiene en cuenta.

Después del primer intento, que sale apenas se aprueba o rechaza el cobro, los reintentos esperan:

ReintentoEspera desde el intento anterior
15 minutos
215 minutos
330 minutos
42 horas
56 horas
624 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 header X-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 occurredAt y paymentCreatedAt para ordenarlos.
  • Responde rápido: confirma con 2xx en 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​