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β
| Event | When it is sent |
|---|---|
terminal.payment.approved | The payment was approved. |
terminal.payment.denied | The 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.
- 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 route | What it does | Response |
|---|---|---|
POST /rest/businesses/commerces/{commerceId}/webhooks | Registers a webhook | 201 with the webhook and its secret |
GET /rest/businesses/commerces/{commerceId}/webhooks | Lists the commerce's webhooks, newest first | 200 |
GET /rest/businesses/commerces/{commerceId}/webhooks/{webhookId} | Gets one webhook | 200 |
PATCH /rest/businesses/commerces/{commerceId}/webhooks/{webhookId} | Updates, pauses or resumes a webhook | 200 |
DELETE /rest/businesses/commerces/{commerceId}/webhooks/{webhookId} | Deletes a webhook | 200 with { "id": "..." } |
Every schema is detailed in the interactive Wallet Gateway reference.
Authentication and Permissionsβ
| Header | Value |
|---|---|
Authorization | Bearer <your application JWT> |
x-user-token | Token of the commerce owner |
- The application needs the
businesses:createBusinesspermission, 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-tokenand 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" }]
}'
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Public HTTPS URL that receives the events. Up to 2048 characters. See URL Rules. |
events | string[] | Yes | At least one of terminal.payment.approved and terminal.payment.denied. |
headers | object[] | No | Up to 5 { name, value } headers sent with every delivery. See Custom Headers. |
{
"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 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
valuecomes back as****followed by its last 4 characters (just****when it has 4 characters or fewer). - Query string values of the
urlcome back as****; parameter names are kept. For example,https://erp.example.com/hooks/migo?token=abc123reads ashttps://erp.example.com/hooks/migo?token=****.
Update, Pause or Resumeβ
PATCH only changes the fields you send:
| Field | Type | Description |
|---|---|---|
url | string | New URL. It is validated again with the same rules. |
events | string[] | Replaces the event list (at least one). |
enabled | boolean | false pauses the webhook and true resumes it. |
headers | object[] | 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:
{ "success": true, "data": { "id": "65f1c2a9e4b0a1b2c3d4e5f6" } }
Limitsβ
- Up to 5 webhooks per commerce.
- The
urlis 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 withX-Migo-,Proxy-orX-Forwarded-.
Values are stored encrypted and only returned masked.
Errorsβ
Errors use the usual envelope, { "success": false, "errors": [{ "code", "message" }] }:
| HTTP | Code | When |
|---|---|---|
400 | 7000 | The 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. |
400 | 7715 | The URL breaks the URL rules. |
400 | 7716 | The 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. |
404 | 7408 | The user is not the commerce owner, or the commerce does not exist. |
404 | 7713 | The webhook does not exist in that commerce. |
409 | 7714 | The commerce already has 5 webhooks (POST only). |
409 | 7717 | The 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:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Migo-Webhooks/1.0, unless you register your own User-Agent as a custom header |
X-Migo-Event | Event type, for example terminal.payment.approved |
X-Migo-Event-Id | Event identifier, equal to the body id |
X-Migo-Timestamp | Send time, in Unix seconds |
X-Migo-Signature | t=<unix>,v1=<hex>; see Verify the Signature |
Your registered custom headers are sent as well.
The 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
| Field | Type | Description |
|---|---|---|
id | string | Event identifier (evt_ + 24 hexadecimal characters). It is stable: the same payment and event type always produce the same id, retries included. |
type | string | terminal.payment.approved or terminal.payment.denied. |
apiVersion | string | Event format version: 2026-10-01. |
createdAt | string | When the event was generated (ISO 8601, UTC). |
data | object | The payment data. |
data
| Field | Type | Description |
|---|---|---|
terminalPaymentId | number | Terminal payment identifier. |
operationId | string | null | Operation identifier, when there is one. |
status | string | approved or denied. |
authorizationCode | string | null | Authorization code. It can be null, especially on denials and alternative payments. |
paymentMethodType | string | card for card-present; for alternative payments, the method identifier. |
amount.subtotal | string | Gross 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.total | string | Optional. 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.currency | string | ISO 4217 alphabetic currency code. |
commerce.id | number | Commerce of the payment. |
branch.id | number | Branch of the payment. |
terminal.id | number | Terminal of the payment. |
terminal.externalId | string | null | External terminal identifier. |
terminal.deviceId | string | null | Device identifier. |
card | object | null | Only 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. |
decline | object | Only on terminal.payment.denied. code (up to 4 alphanumeric characters) and reason (up to 120 characters); either can be null. |
occurredAt | string | When the event was emitted (ISO 8601, UTC). |
paymentCreatedAt | string | null | When 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:
- 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.
- Split
tandv1out of the header. - Compute
HMAC-SHA256(secret, t + "." + body)as hexadecimal. The key is the fullsecret, including thewhsec_prefix. - Compare the result with
v1in constant time. - Reject the event if
|now β t|is greater than 300 seconds. Each attempt is signed again with its ownt, so retries pass this check too. - Deduplicate by
idbefore processing (see Delivery Guarantees).
If verification fails, answer 400 and do not process the event.
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); // process outside the response
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) # 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
3xxcounts as a failure. - Your response body is ignored.
- Any other status (including
4xxsuch as400,403,404,413or429), a timeout or a connection error counts as a failure and is retried on the schedule below. Each retry is signed again.Retry-Afteris not honoured.
After the first attempt, sent as soon as the payment is approved or denied, retries wait:
| Retry | Wait since the previous attempt |
|---|---|
| 1 | 5 minutes |
| 2 | 15 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 6 hours |
| 6 | 24 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 theX-Migo-Event-Idheader, which carries the same value). - No guaranteed order: events can arrive in a different order than the payments, especially with retries. Use
occurredAtandpaymentCreatedAtto order them. - Answer fast: acknowledge with
2xxas 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.
Relatedβ
- Transaction flow β how a payment is approved or denied on the terminal.
- Reverse an authorized charge β reversals produce no event.
- Error catalog β every error code.