Webhooks

Transfero Checkout does not send outbound partner webhooks. Notifications come from Ultra to an endpoint you register on your Ultra account. After each event, call the Partner API status GET to reconcile — do not treat the webhook alone as the source of truth for Checkout state.

Events and correlation

Ultra event	Flow	Correlate with	Then query
`otc.trade.settled` / `otc.trade.cancelled`	Crypto swap (currency ≠ BRZ)	`tradeId` from `POST .../payment` (also `settlement.tradeId`)	Order status
`pix.deposit.*`	PIX-in (when applicable)	`endUserId` / tag `user:{orderId}`	Order status
`pix.withdrawal.*`	PIX withdrawal	Withdrawal ids / tags from the Ultra payload	Withdrawal status

sequenceDiagram
    participant Ultra as Ultra
    participant Partner as Partner_webhook
    participant Api as Partner_API

    Note over Ultra,Partner: Crypto swap settlement (≠ BRZ)

    Ultra->>Partner: otc.trade.settled (tradeId, eventId)
    Partner->>Partner: Verify signature, dedupe eventId
    Partner->>Api: GET /orders/by-external-id/{externalId}
    Note right of Partner: Or look up by tradeId
    Api-->>Partner: settlement.status Settled
    Partner->>Partner: Release delivery / update ERP

    Note over Ultra,Partner: PIX withdrawal

    Ultra->>Partner: pix.withdrawal.settled (eventId)
    Partner->>Partner: Verify signature, dedupe eventId
    Partner->>Api: GET /withdrawals/by-external-id/{externalId}
    Api-->>Partner: status Completed

Important gaps

Milestone 1 (buyer crypto paid) is not covered by Ultra trade webhooks — keep short polling while checkout is open.
BRZ payments have no OTC trade and no otc.trade.* event. Persist nothing from tradeId (it is null) and rely on status polling (and any deposit events if you use Ultra PIX).

Receptor requirements

HTTPS with a publicly trusted certificate; no redirects; respond 2xx within ~10 seconds.
Verify X-Ultra-Signature with the signing secret of your webhook endpoint.
Deduplicate by eventId (Ultra may retry).
You receive the Ultra payload as-is; map business meaning via Partner API status fields.

Ask your Transfero contact to register (or help you register) a second Ultra webhook endpoint subscribed to the events above for your environment.