Configuring Webhooks

Webhooks are the primary method for receiving updates from our API. They are given the highest priority, ensuring updates are delivered to them first. Therefore, it is crucial to properly configure your webhooks to ensure you receive updates promptly and reliably. We recommend that you do not use one of the public API keys to configure the webhook in the testing environment, as this makes configuration difficult since any user can use them.

Webhooks configuration

Request

curl --location --request POST 'https://apisandbox.delbank.com.br/baas/api/v1/webhooks' \
--header 'x-delbank-api-key: {apiKey}' \
--header 'x-delfinance-account-id: {accountId}'

Headers

Name	Description
x-delbank-api-key	Required. API key
x-delfinance-account-id	Required. The Delfinance bank account number

Body

Name	Type	Description
eventType	enum	Required. Type of event to be monitored/listened
url	string	Required. API URL of the client system that will receive the webhook information
authorizationScheme	enum	Type of authorization that must be used when executing the endpoint call (according to the url field). Domains: - BASIC - BEARER - HEADER
authorization	string	Information that will be sent in the request header to the endpoint

URL Validation

The url field must follow these rules to be accepted by the API:

• Must start with http:// or https://
• Must contain a valid domain name (e.g., example.com or www.example.com)
• The domain name must be between 1 and 256 characters long
• The top-level domain (e.g., .com, .br) must be between 1 and 6 characters long
• May optionally contain a valid path, query parameters, or fragments at the end

Example

Configuring the webhook with Authentication Basic

{
  "eventType": "PIX_RECEIVED",
  "url": "https://example.com.br/webhooks/v1/bankslips",
  "authorization": "bG9naW46cGFzc3dvcmQ=",
  "authorizationScheme": "BASIC"
}

Configuring the webhook with Authentication Bearer

{
  "eventType": "PIX_RECEIVED",
  "url": "https://example.com.br/webhooks/v1/bankslips",
  "authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authorizationScheme": "BEARER"
}

Configuration Maintenance

Endpoint	HTTP Method	Description
https://apisandbox.delbank.com.br/baas/api/v1/webhooks	GET	Query all the registered webhooks registered by the API Key used in the requisition.
https://apisandbox.delbank.com.br/baas/api/v1/webhooks/:ID	GET	Query webhook by ID
https://apisandbox.delbank.com.br/baas/api/v1/webhooks/:ID	PATCH	Update webhook by ID (Uses the same payload as the register webhook)
https://apisandbox.delbank.com.br/baas/api/v1/webhooks/:ID	DELETE	Remove registered Webhook by ID

Event Types

Below is a list of event types and their meaning

Name	Description	Link
CHARGE_PAID	Paid bankslip	Click here
PIX_RECEIVED	Pix received. (New webhook flow for Pix receiving only)	Click here
PIX_PAYMENT_UPDATED	Update payment status for Pix.	Click here
PIX_REFUNDED	Event for refunds received	Click here
PIX_REFUND_PAYMENT_UPDATED	Event for errors in refunds sent	Click here
TRANSFER_INTERNAL_CREDITED	Event for internal transfer received	Click here
TRANSFER_INTERNAL_DEBITED	Event for internal transfer sent	Click here
TRANSFER_EXTERNAL_CREDITED	Event for external transfer received (TED)	Click here
TRANSFER_EXTERNAL_DEBITED	Event for external transfer sent (TED)	Click here
INFRACTION_NOTIFICATION_CREATED	Event for created Infraction notifications	Click here
INFRACTION_NOTIFICATION_UPDATED	Event for updated Infraction notifications	Click here
ACCOUNT_STATUS_UPDATED	Event for account status changes	Click here
WHITELABEL_CUSTOMER_DOCUMENTATION_REJECTED	Rejected documents for a new created account	Click here
WHITELABEL_CUSTOMER_APPROVED	Customer approved and bank account created	Click here