Skip to main content

Webhooks FAQ

Short answers to the questions integrators ask most about webhook delivery. Each answer links to the page with the full detail.

My endpoint answered with an error, such as 429. Will Avenia send the event again?​

No. A non-2xx answer is recorded as an unacknowledged attempt and is not sent again. Only an endpoint that can't be reached at all gets a brief retry. Answer 2xx fast, process the event afterwards, and recover anything you missed from the event and attempt lists.

See When your endpoint fails.

How do I get events I missed, or resend a ticket's webhooks?​

POST /v2/account/tickets/{ticketId}/resend-webhooks sends all of that ticket's events again with their original event.id. Add ?subAccountId= for a sub-account's ticket; tickets older than 30 days can't be resent. To find what you missed, list events with GET /v2/notifications/webhooks/events?createdAfter=<epoch milliseconds>, or read the ticket directly.

See When your endpoint fails.

I received ticket events for a PIX I never created a ticket for. What is it?​

A PIX sent to your static key or BR Code creates a ticket automatically, with reason Pix deposit without ticket, and sends the usual events. An on-chain deposit to your deposit address does the same, with Blockchain deposit without ticket.

See Questions that come up.

How do I tell a pay-in from a payout in a webhook?​

There's no direction field. Read data.ticket.quote.inputPaymentMethod and outputPaymentMethod, or check which block the ticket has: brazilianFiatSenderInfo for a PIX received, brazilianFiatReceiverInfo for a PIX sent.

See Questions that come up.

Is there a webhook when an UNPAID ticket expires?​

No. Nothing changes at expiration: the ticket stays UNPAID and no event is sent. A cancellation you make yourself doesn't send one either. To close an expired ticket on your side, cancel it with PATCH /v2/account/tickets/{id}/cancel.

See Expired tickets.

Is it DELIVERY_SUCCESS or DELIVERY-SUCCESS?​

DELIVERY-SUCCESS. Event names use hyphens, for example DEPOSIT-FAILED, TICKET-COMPLETE and DELIVERY-PARTIAL-FAILED. The name is in data.type.

See What arrives and the ticket event list.

Where is the payer's tax ID in the webhook?​

In the ticket's sender block: data.ticket.brazilianFiatSenderInfo for a PIX deposit. Ticket events carry the whole ticket, with the same fields as GET /v2/account/tickets/{id}.

See Questions that come up.

Can the same event arrive twice?​

Yes. An event can be delivered more than once, and the events of one ticket can arrive out of order. Deduplicate by event.id, which stays the same when an event is delivered again or resent. Decide from the ticket status in the payload, not from the order of arrival.

See How to handle them.