Skip to main content
POST
Setup

Setup

The system allows the registration of webhook URLs to receive automatic notifications about relevant events. A webhook is one URL that receives one or more events: send every event the URL should receive in the events list. Webhook URL: HTTPS address where the events will be delivered.
Supported events: onboarding, payin, payout, kyc
Notification format: JSON payload sent via HTTP request
Request method: All notifications will be sent exclusively using the POST method
The registered URL overrides the URL sent in each request. Once a webhook is registered for the payin or payout event, every webhook of that event is delivered to the registered URL, and the notification_url / callback_url sent when creating a transaction is ignored. The same applies to all Payin and Payout webhooks — status updates, refunds and Data Qualifications. The URL sent in the request is only used when no webhook is registered for the event.For the kyc event, the registered URL replaces the KYC callback URL previously configured by our Customer Experience team.Registered deliveries are sent with the x-webhook-wp-type and x-webhook-wp-timestamp headers (plus x-webhook-wp-signature when a secret is set). See Webhook Signature.
Registering, updating or removing a webhook may take up to 5 minutes to take effect. Until then, webhooks keep being delivered to the previous destination.

Subaccounts without a webhook

A subaccount without its own webhook uses the webhook of its main account. For the payin, payout and kyc events, when a subaccount has no webhook registered for the event, its notifications are delivered to the webhook its main account registered for that same event — to the main account’s URL, signed with the main account’s secret.
  • The fallback is decided per event: a subaccount with its own payin webhook and no payout webhook receives payin on its own URL and payout on the main account’s.
  • Only when neither the subaccount nor its main account has a webhook for the event are the notifications sent to the transaction’s notification_url (payin and payout) or to the KYC callback URL configured by our Customer Experience team (kyc).
  • The onboarding event has no fallback: it is always delivered to the onboarding webhook of the account that requested the onboarding.
To send a subaccount’s notifications somewhere else, register a webhook for it with account_id.

Request Body

string[]
required
Events this webhook will receive. Send at least one event, without repeating any.Allowed values: onboarding, payin, payout, kyc
  • onboarding: notifications about the account onboarding status. Sent without the x-webhook-wp-type header.
  • payin: notifications about Payin status changes (Pix — including Pix key credits and Automatic Pix —, Boleto, Credit Card and refunds). x-webhook-wp-type values:
    • payin-pix: status update of a Pix Payin (including Automatic Pix and Pix key credits)
    • payin-boleto: status update of a Boleto Payin
    • payin-credit-card: status update of a Credit Card Payin
    • payin-refund: refund of a received Pix Payin, requested by the merchant
  • payout: notifications about Payout status changes, refunds and Data Qualifications. x-webhook-wp-type values:
    • payout-pix: status update of a Pix Payout
    • payout-ted: status update of a TED Payout
    • payout-qrcode: status update of a Pix QR Code Payout
    • payout-refund: Pix Payout returned to the merchant
    • payout-customer-refund: status update of a customer refund (Reembolso) paid out to your customer
    • payout-data-qualification: status update of a Data Qualification
  • kyc: notifications about KYC status changes. See KYC Webhook. x-webhook-wp-type value:
    • kyc: status update of a KYC
See Webhook types for details.Each event can be on only one webhook per account: the same event can be registered on your merchant and on each of its subaccounts, but not on two URLs of the same account. Sending an event that another webhook of the target account already receives fails with 422 and the webhook_already_exists code on that item (for example events.1) — move the event with Update instead.Example: ["payin", "payout"]
string
required
Endpoint URL that will receive the notifications of every event in events. The URL identifies the webhook: use it to update or remove the webhook later.Each URL can be registered only once per account (URLs that differ only in letter case count as the same URL). Registering a URL that the target account already has fails with 422 and the webhook_url_already_exists code — add the new events to the existing webhook with Update instead.Maximum length: 120 charactersExample: https://my-url.com/test
string
Secret used to sign the payin, payout and kyc webhooks with HMAC-SHA256. When provided, every webhook delivered to this URL includes the x-webhook-wp-signature header.Maximum length: 255 characters. Use a long, randomly generated value.Example: whsec_9f8e7d6c5b4a3210
integer
ID of the account the webhook will be registered for: your own merchant or one of its subaccounts. Use it to register the webhooks of a subaccount with your own credentials.When omitted, the webhook is registered for your merchant (the authenticated account).If the account does not exist or is not linked to your merchant, the request fails with 422 and the invalid_account code.Example: 4521

Response

integer
ID of the account the webhook was registered for.Example: 4521
string[]
Events the webhook receives.Allowed values: onboarding, payin, payout, kycExample: ["payin", "payout"]
string
Endpoint URL that was registered to receive webhook notifications.Example: https://my-url.requestcatcher.com/test
string
Secret used to sign the webhooks delivered to this URL, or null if none is set.Example: whsec_9f8e7d6c5b4a3210

Request Example

Webhook Payload

When an onboarding event occurs, a POST request will be sent to your webhook URL:
The account_id is only returned the first time in the webhook when the status is active.
When the new Onboarding Documents Flow is enabled for a merchant, the payload for the pending_documents status also includes a documents array with the documents the client must send.
Your webhook endpoint must return a 200 OK status code to acknowledge receipt. If the endpoint fails or returns an error, delivery is retried up to 3 times, every 15 minutes.