Overview

MuPag delivers events to the merchant HTTPS endpoint with POST and Content-Type: application/json. The body is the envelope {"id","type","data"}. There is no User-Agent. The connection does not follow redirects: a 3xx comes back as a non-2xx response and the delivery is abandoned.

Where the secret comes from

The API-key OpenAPI contract does not register endpoints. The secret is created in the QA dashboard, in the merchant Webhooks section. Creation shows secret once, as whsec_ plus the token. Rotation also shows the new secret once. Listing does not include the secret. sk_* and pk_* tokens do not perform that registration.

The URL must be public HTTPS, without userinfo, and without a private host, localhost, a .local suffix, link-local, or ULA. During registration the sender posts a ping whose exact body is {"id":"webhook.test","type":"webhook.test","data":{"ping":true}}. A 2xx status marks the endpoint verified. Any other result leaves pending_verification. The endpoint and the secret are kept in both cases. webhook.test is only that ping; it is not a Kafka event.

Delivery headers

• MuPag-Signature: t=<epoch seconds>,v1=<lowercase 64-character HMAC-SHA256>
• X-Gateway-Signature: temporary alias with the same value as MuPag-Signature
• X-Gateway-Event-Id: the same value as body id
• X-Gateway-Timestamp: the same epoch used in the signature
• Accept: */*
• Connection: close
• Host: the original hostname

Each attempt applies 10 seconds to the TCP connect and to each socket read (SO_TIMEOUT). That is not a wall-clock limit for the whole attempt: a slow body can take longer than 10 seconds. Success is any status from 200 through 299.

What to do on receipt

1. Keep the raw body. Do not reformat the JSON.
2. Validate MuPag-Signature as described in Signature.
3. Deduplicate on id.
4. Persist the effect, then respond 2xx.

The sender does not impose a tolerance window. verify takes the caller's tolerance, and the unit tests use 300 seconds. Production delivery does not call verify and does not fix that number.

Events with an invalid contract, or a body above 65536 UTF-8 bytes, go to an internal quarantine and are not delivered. There is no public dead-letter API.

Retry details are in Retries. Subscribed types are in Event catalog. Deduplication is in Replay safety.