Skip to main content
POST
Setup

Setup

The system allows the registration of webhook URLs to receive automatic notifications about relevant events. Webhook URL: HTTPS address where the events will be delivered.
Supported events: onboarding, payin, payout
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.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.

Request Body

string
required
Type of event that will trigger the webhook.Allowed values: onboarding, payin, payout
  • 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
See Webhook types for details.Only one webhook can be registered per event.Example: payin
string
required
Endpoint URL that will receive the webhook notifications for the selected event.URL characters: a-z, A-Z charactersMaximum length: 120 charactersExample: https://my-url.com/test
string
Secret used to sign the payin and payout webhooks with HMAC-SHA256. When provided, every webhook for this event includes the x-webhook-wp-signature header.Maximum length: 255 characters. Use a long, randomly generated value.Example: whsec_9f8e7d6c5b4a3210

Response

string
Type of event that will trigger the webhook.Allowed values: onboarding, payin, payoutExample: payin
string
Endpoint URL that was registered to receive webhook notifications.Example: https://my-url.requestcatcher.com/test
string
Secret used to sign the webhooks for this event, 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.