Skip to main content
Migo Docs

Payment Webhooks

Register an HTTPS URL for your commerce and Migo sends it a signed POST every time a terminal payment of that commerce is approved or denied. Use it to reconcile in your ERP or backend without polling the history.

A webhook is registered per commerce and receives the payments of all its branches and terminals, both card-present and alternative payments.

Events​

EventWhen it is sent
terminal.payment.approvedThe payment was approved.
terminal.payment.deniedThe payment was denied before it was approved (it was still created). A payment already notified as approved never produces a denial.

Each webhook only receives the events listed in its events.

What does not produce an event
  • Cancellations and reversals emit no event, including the reversal of an authorized charge.
  • A payment already notified as approved can change afterwards (for example, be cancelled or reversed) without another event. If your reconciliation depends on the final state, check it against the transaction history.

Manage Webhooks​

The five routes live on the Wallet Gateway (https://api.ali.app/rest in production, https://ali-qa.ali.app/rest in QA), under /rest/businesses/commerces/{commerceId}/webhooks.

Method and routeWhat it doesResponse
POST /rest/businesses/commerces/{commerceId}/webhooksRegisters a webhook201 with the webhook and its secret
GET /rest/businesses/commerces/{commerceId}/webhooksLists the commerce's webhooks, newest first200
GET /rest/businesses/commerces/{commerceId}/webhooks/{webhookId}Gets one webhook200
PATCH /rest/businesses/commerces/{commerceId}/webhooks/{webhookId}Updates, pauses or resumes a webhook200
DELETE /rest/businesses/commerces/{commerceId}/webhooks/{webhookId}Deletes a webhook200 with { "id": "..." }

Every schema is detailed in the interactive Wallet Gateway reference.

Authentication and Permissions​

HeaderValue
AuthorizationBearer <your application JWT>
x-user-tokenToken of the commerce owner
  • The application needs the businesses:createBusiness permission, and so does the owner.
  • Only the commerce owner can manage its webhooks. Any other user linked to the commerce gets 404.
  • Applications with the ADMIN or SUPPORT role may omit x-user-token and manage any commerce.

Register a 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" }]
}'
FieldTypeRequiredDescription
urlstringYesPublic HTTPS URL that receives the events. Up to 2048 characters. See URL Rules.
eventsstring[]YesAt least one of terminal.payment.approved and terminal.payment.denied.
headersobject[]NoUp to 5 { name, value } headers sent with every delivery. See Custom Headers.
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>"
}
}
Store the secret now

secret only appears in this response. No later read returns it, and it cannot be retrieved or regenerated. If you lose it, delete the webhook and register it again: the new registration comes with a new secret.

List and Get​

GET returns the same object without secret, with sensitive values masked:

  • Each header value comes back as **** followed by its last 4 characters (just **** when it has 4 characters or fewer).
  • Query string values of the url come back as ****; parameter names are kept. For example, https://erp.example.com/hooks/migo?token=abc123 reads as https://erp.example.com/hooks/migo?token=****.

Update, Pause or Resume​

PATCH only changes the fields you send:

FieldTypeDescription
urlstringNew URL. It is validated again with the same rules.
eventsstring[]Replaces the event list (at least one).
enabledbooleanfalse pauses the webhook and true resumes it.
headersobject[]Replaces the whole list. [] removes every header.
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 }'

The secret never changes on a PATCH: pausing and resuming keeps the same secret.

While paused, the webhook receives no new events. Deliveries already queued keep their retry schedule; to drop them, delete the webhook.

Delete​

DELETE removes the webhook; its pending deliveries are no longer sent (one already on its way at that instant may still arrive). The response only carries the id:

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

Limits​

  • Up to 5 webhooks per commerce.
  • The url is unique within the commerce: you cannot register two webhooks with the same URL.

URL Rules​

The URL is validated when you register it and every time you change it. It must:

  • use https;
  • use port 443 (no port in the URL, or :443);
  • carry no username or password;
  • have a public host name (a domain), never a literal IP;
  • resolve only to public IP addresses: if any address of the domain is private, local, reserved or for documentation, it is rejected.

Resolution is repeated on every delivery. If at that moment the domain points to a non-public address, that delivery is dropped without retries.

Custom Headers​

You can add up to 5 headers so your endpoint can authenticate the call (for example, your own API key):

  • Name: 1 to 64 characters, only letters, digits and -. It cannot repeat within the list (case-insensitive).
  • Value: up to 512 printable ASCII characters or tab. No line breaks and no non-ASCII characters.
  • Reserved names (case-insensitive): Host, Content-Length, Content-Type, Transfer-Encoding, Connection, Content-Encoding, Expect, Upgrade, TE, Trailer, Keep-Alive, Forwarded, and any name starting with X-Migo-, Proxy- or X-Forwarded-.

Values are stored encrypted and only returned masked.

Errors​

Errors use the usual envelope, { "success": false, "errors": [{ "code", "message" }] }:

HTTPCodeWhen
4007000The body does not have the expected shape: url or events missing, events empty or with an unknown event, url longer than 2048 characters, enabled not a boolean.
4007715The URL breaks the URL rules.
4007716The headers break the header rules or there are more than 5.
401β€”The application JWT is missing or invalid, or x-user-token is missing on an application that is neither ADMIN nor SUPPORT.
403β€”The application or the user lacks the businesses:createBusiness permission, or an application that is neither ADMIN nor SUPPORT calls without a user.
4047408The user is not the commerce owner, or the commerce does not exist.
4047713The webhook does not exist in that commerce.
4097714The commerce already has 5 webhooks (POST only).
4097717The commerce already has a webhook with that URL.

When several problems occur at once, POST reports only one, in this order: headers (7716), URL (7715), limit (7714) and duplicated URL (7717).

The Delivery​

Each event arrives as a POST to your URL with these headers:

HeaderValue
Content-Typeapplication/json
User-AgentMigo-Webhooks/1.0, unless you register your own User-Agent as a custom header
X-Migo-EventEvent type, for example terminal.payment.approved
X-Migo-Event-IdEvent identifier, equal to the body id
X-Migo-TimestampSend time, in Unix seconds
X-Migo-Signaturet=<unix>,v1=<hex>; see Verify the Signature

Your registered custom headers are sent as well.

The 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

FieldTypeDescription
idstringEvent identifier (evt_ + 24 hexadecimal characters). It is stable: the same payment and event type always produce the same id, retries included.
typestringterminal.payment.approved or terminal.payment.denied.
apiVersionstringEvent format version: 2026-10-01.
createdAtstringWhen the event was generated (ISO 8601, UTC).
dataobjectThe payment data.

data

FieldTypeDescription
terminalPaymentIdnumberTerminal payment identifier.
operationIdstring | nullOperation identifier, when there is one.
statusstringapproved or denied.
authorizationCodestring | nullAuthorization code. It can be null, especially on denials and alternative payments.
paymentMethodTypestringcard for card-present; for alternative payments, the method identifier.
amount.subtotalstringGross amount charged to the card, as a decimal string with no fixed number of decimals ("2", "125.5", "3.35"). Parse it with a decimal type, not floating point.
amount.totalstringOptional. Net amount after commissions, same format as subtotal. It only travels once the payment has been settled; approved and denied events are emitted before settlement, so today it is usually absent. "0" is never sent. subtotal is not what the commerce receives: do not credit it as net.
amount.currencystringISO 4217 alphabetic currency code.
commerce.idnumberCommerce of the payment.
branch.idnumberBranch of the payment.
terminal.idnumberTerminal of the payment.
terminal.externalIdstring | nullExternal terminal identifier.
terminal.deviceIdstring | nullDevice identifier.
cardobject | nullOnly bin (first 6 digits), last4 and brand; any of the three can be null. It is null for alternative payments or when there is no card data. The full card number, the holder and any other card data are never sent.
declineobjectOnly on terminal.payment.denied. code (up to 4 alphanumeric characters) and reason (up to 120 characters); either can be null.
occurredAtstringWhen the event was emitted (ISO 8601, UTC).
paymentCreatedAtstring | nullWhen the payment was started (ISO 8601, UTC).

Verify the Signature​

Every delivery is signed with the webhook secret. The header looks like:

X-Migo-Signature: t=1790867045,v1=5f2b0c...e91a

To verify it:

  1. Take the raw body, exactly the bytes received, before parsing the JSON. If you parse it and serialize it again, the signature will not match.
  2. Split t and v1 out of the header.
  3. Compute HMAC-SHA256(secret, t + "." + body) as hexadecimal. The key is the full secret, including the whsec_ prefix.
  4. Compare the result with v1 in constant time.
  5. Reject the event if |now βˆ’ t| is greater than 300 seconds. Each attempt is signed again with its own t, so retries pass this check too.
  6. Deduplicate by id before processing (see Delivery Guarantees).

If verification fails, answer 400 and do not process the event.

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); // process outside the response
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) # process outside the response
return "", 200

Retries​

A delivery succeeds when your endpoint answers with a 2xx status within 10 seconds.

  • Redirects are not followed: a 3xx counts as a failure.
  • Your response body is ignored.
  • Any other status (including 4xx such as 400, 403, 404, 413 or 429), a timeout or a connection error counts as a failure and is retried on the schedule below. Each retry is signed again. Retry-After is not honoured.

After the first attempt, sent as soon as the payment is approved or denied, retries wait:

RetryWait since the previous attempt
15 minutes
215 minutes
330 minutes
42 hours
56 hours
624 hours

Each wait can stretch by up to about 5 extra minutes. That makes 7 attempts in total over about 33 hours; if none succeeds, the event is dropped and never sent again. These values (and the per-commerce webhook limit and the timeout) are Migo's current configuration; any change is announced in the changelog.

Delivery Guarantees​

  • At least once: the same event can arrive more than once, for example if your endpoint processed it but answered late. Always deduplicate by id (or by the X-Migo-Event-Id header, which carries the same value).
  • No guaranteed order: events can arrive in a different order than the payments, especially with retries. Use occurredAt and paymentCreatedAt to order them.
  • Answer fast: acknowledge with 2xx as soon as the signature checks out and process the event afterwards. If your logic takes longer than 10 seconds, the attempt counts as failed and is sent again.
  • The payment does not depend on the webhook: a down or slow endpoint does not affect the payment or its response on the terminal.