Webhooks

Learn how to start using webhooks notifications.

Webhooks are notifications about API events, sent as they occur. You can configure webhook endpoints via the API to be notified about events that happen in your account or connected accounts.

The Webhook object

Attributes

Body
Headers
Body

Property

Type

Description

uuid

String

Webhook unique identifier (autogenerated).

name

String

Webhook name.

description

String

Webhook description.

events

String

List of available events (for subscriber all events, send only ALL string).

url

String

Webhook endpoint URL.

is_active

Boolean

Webhook enabled or disabled.

Headers

Property

Type

Description

auth

String

Two types of Authentication header:

  • Basic: requires basic_username and basic_password. This header will be sent as Basic bas64(basic_username:basic_password)

  • Secret-key: only requires the secret key string. This header will be sent as Bearer secret_key

custom

String

Other constants headers that your endpoint requires.

Example Object

Webhook Object
Webhook Object
{
"uuid": "ISGW-4-585a16b094d64ae99d019caf27795536",
"name": "webhook_1",
"description": "My webhook #1",
"events": [
"TRANSACTION_EVENT"
],
"headers": {
"auth": {
"basic_username": "my_user",
"basic_password": "my_pass",
"secret_key": "my_secret_key"
},
"custom": {
"header_key_1": "value_1",
"header_key_2": "value_2"
}
},
"url": "http://merchant-host.com/callback",
"is_active": true
}

post
Create notifications

https://issuing-api.dlocal.com/issuing/webhooks
Request
Response
Request
Body Parameters
name
required
string
Webhook name.
description
optional
string
Webhook description.
url
required
string
Webhook endpoint URL.
events
required
string
List of available events (for subscriber all events, send only ALL string).
headers
optional
string
Optional headers.
is_active
required
boolean
Webhook enabled or disabled.
Response
200: OK
{
"uuid": "ISGW-4-86d652010e3c4a1db61ef6420ebf4197",
"name": "webhook_1",
"description": "My webhook #1",
"url": "http://merchant-host.com/callback",
"events": [
"TRANSACTION_EVENT"
],
"headers": {
"auth": {},
"custom": {
"header_key_1": "value_1"
}
},
"is_active": false,
"creation_date": "2021-08-23T20:53:06.276Z",
"last_updated": "2021-08-23T20:53:06.276Z"
}

The headers only are shown when you create this webhook. You don't have to modify the headers later.

Request

{
"name": "webhook_1",
"description": "My webhook #1",
"url": "http://merchant-host.com/callback",
"events": [
"TRANSACTION_EVENT"
],
"headers": {
"custom": {
"header_key_1": "value_1"
}
},
"is_active": false
}

put
Update webhooks

https://issuing-api.dlocal.com/issuing/webhooks/{webhook_uuid}
Request
Response
Request
Path Parameters
webhook_uuid
optional
string
Webhook unique identifier.
Body Parameters
name
required
string
Webhook name.
description
optional
string
Webhook description.
url
required
string
Webhook endpoint URL.
events
required
string
List of available events (for subscriber all events, send only ALL string).
is_active
required
string
Webhook enabled or disabled.
Response
200: OK
{
"uuid": "ISGW-4-86d652010e3c4a1db61ef6420ebf4197",
"name": "webhook_1",
"description": "My webhook #1 - modified",
"url": "http://merchant-host.com/callback",
"events": [
"ALL"
],
"is_active": true,
"creation_date": "2021-08-23T20:54:34.276Z",
"last_updated": "2021-08-23T20:54:34.276Z"
}

All of the fields will be updated.

Request

{
"name": "webhook_1",
"description": "My webhook #1 - modified",
"url": "http://merchant-host.com/callback",
"events": [
"ALL"
],
"is_active": true
}

get
Retrieve a notification

https://issuing-api.dlocal.com/issuing/webhooks/{webhook_uuid}
Request
Response
Request
Path Parameters
webhook_uuid
required
string
Webhook unique identifier.
Response
200: OK
{
"uuid": "ISGW-4-86d652010e3c4a1db61ef6420ebf4197",
"name": "webhook_1",
"description": "My webhook #1 - modified",
"url": "http://merchant-host.com/callback",
"events": [
"TRANSACTION_EVENT"
],
"is_active": true,
"creation_date": "2021-08-23T20:54:34.276Z",
"last_updated": "2021-08-23T20:54:34.276Z"
}

get
List all the notifications

https://issuing-api.dlocal.com/issuing/webhooks
Request
Response
Request
Query Parameters
page_size
optional
integer
Limit to webhooks to retrieve. Default is 100 and max is 500.
page_number
optional
integer
Webhooks to start. By default is 0.
Response
200: OK
{
"content": [
{
"uuid": "ISGW-4-86d652010e3c4a1db61ef6420ebf4197",
"name": "webhook_1",
"description": "My webhook #1 - modified",
"url": "http://merchant-host.com/callback",
"events": [
"TRANSACTION_EVENT"
],
"is_active": true,
"creation_date": "2021-08-23T20:54:34.276Z",
"last_updated": "2021-08-23T20:54:34.276Z"
},
{
...
}
]
}

delete
Delete webhooks

https://issuing-api.dlocal.com/issuing/webhooks/{webhook_uuid}
Request
Response
Request
Path Parameters
webhook_uuid
required
string
Webhook unique identifier.
Response
204: No Content