Webhooks

🚧 Webhook Sandbox

At the moment, the webhooks feature in the sandbox environment is under development and is therefore not available to all users.

What are webhooks?

Webhooks are resources for exchanging information between two systems at the moment of an event using HTTP messages. They can be used to automate tasks by subscribing to product events, which notify your integration. In the Developer Area, you can access the webhooks of each application.

Webhook endpoint

The webhook endpoint is the address your integration uses to be notified of the events it subscribes to. The endpoint must meet a few requirements:

• Comply with the HTTPS protocol;
• Not use custom ports. Our server will only make requests to the default port of the HTTPS protocol.

POST https://example.com/notifications

Events

Webhook events are the notifications sent by the product about some process that is taking place.

A webhook event has this structure:

Attribute	Type	Description
webhookId	guid	Id of the webhook that receives the notification.
event	string	Type of the notified event.
data	object	Object with data associated with the event. The object's structure is defined by the type of event notified.

In this example, the data object is defined by the transactions.debit event type, indicating a debit in the digital account.

{
    "webhookId": "bb2ae4c5-8094-4f3c-b0e0-02646ba6e5e3",
    "event": "transactions.debit",
    "data": {
        //webhook payload 
    }
}

x-correlation-id

The webhook will include the x-correlation-id field in the header. The value of x-correlation-id is the same across every retry.

Receiving webhooks

When you configure an endpoint, you will receive notifications for the chosen event types. The subscription behavior is determined by how you receive and respond to them via HTTP status.

Status Code	Description	Action
200	Success	Webhook delivered.
4XX	Delivery failure	Indicates that our agent was blocked by your server when attempting delivery. Proceeds to the retry protocol.
5XX	Client server unavailable	Indicates that your server is unavailable to our agent. Proceeds to the retry protocol.

*The application has 10 seconds to respond to a webhook before the message fails.

Consent

For security reasons, your endpoint will only receive events related to the product scopes that were part of a token generation flow for your application. For example, if your application has a webhook with the balance and account statement events subscribed but never performed the generation flow with these tokens, the agent will not send these events to your endpoint.

So, if you are not receiving an event you have subscribed to, make sure to perform the token generation flow with the scope corresponding to the product that emits the event.

Retry protocol

The retry protocol is a way to ensure that occasional instabilities in your system do not prevent webhook delivery.

When a 4XX or 5XX status code is received, our agent will attempt to resend the webhook up to three more times within 10 minutes. If it does not succeed, the status code obtained on the last attempt is attached to the delivery attempt, which becomes available in the webhook management panel and can be reprocessed manually by the user.

Tags

Tags in the BTG Pactual Empresas systems are key:value pairs that act as identifiers in webhook responses. They are sent in the payload of the events triggered by our system to make it easier for you to manage the events you receive.

Webhook message example

POST /notifications HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer ba143409-d498-4ac4-a6ae-b97d44a19e3f
//The authorization header is filled with your webhook secret

{
    "webhookId": "bb2ae4c5-8094-4f3c-b0e0-02646ba6e5e3",
    "event": "transactions.debit",
    "data": {
        "accountId": "37297902000141-208-50-003886850",
        "date": "2022-03-02T22:01:55.274Z",
        "creditDebitIndicator": "DEBIT",
        "amount": 30900,
        "currency": "BRL",
        "transactionId": "33449743"
    }
}

Retries

After an error, the webhook will include the correlation-id field with a code that will not change.