Webhooks

Configuration error codes for the /v1/webhook routes, and how API statuses map to the events delivered to your endpoint.

The event catalogue and payloads are in Webhook events; delivery rules and authentication are in Webhooks overview.

API status ↔ webhook event

The API and the webhook payload use different vocabularies for the same outcome. Map them explicitly instead of comparing strings across the two.

Operation	API final status	Typical webhook
Deposit	`PAID`	`pixChargePaid` → `paid`
Deposit	`EXPIRED`	`pixChargeExpired` → `expired`
Withdraw	`SUCCESS`	`pixWithdrawSuccess` → `success`
Withdraw	`REJECTED` / `FAILED`	`pixWithdrawFailed` → `rejected` / `failed`
Refund	`REFUNDED`	`pixRefundSuccess` → `success`
Refund	`NOT_EXECUTED`	`pixRefundFailed` → `failed`

`rejectedReason`	Description
`EmissaoExpirada`	Charge issuance expired.
`LiquidacaoExpirada`	Settlement window expired.
(other)	Charge rejected — see `rejectedDescription` in the payload.

Error code	Description
`invalid_value`	Invalid request body, URL too long, empty bearer token, missing notification id, or delete/resend failed.
`invalid_event`	One or more values in `webhookEvents` are not official event names.
`invalid_protocol`	Webhook URL must use HTTPS.
`invalid_auth_type`	Authentication type must be `basic` or `bearer`.
`mtls_not_configured`	mTLS is required on the URL but is not configured.
`webhook_unreachable`	Probe request to the URL failed (network).
`webhook_timeout`	Probe request to the URL exceeded the timeout.
`webhook_error`	Probe request to the URL failed.
`webhook_http_error`	URL returned a non-success HTTP status during probe.
`webhook_no_response`	No response received from the URL during probe.

Error code	Description
`webhook_not_found`	Webhook configuration or notification record not found.

Error code	Description
`invalid_value`	Notification is not eligible for resend.

Error code	Description
`internal_error`	Internal error while processing notification query or resend.