Create Webhook EndPoint

Create Webhook EndPoint

POST{{Environment_URL}}/events/v1/webhooks

This endpoint allows you to register a new webhook endpoint that will receive event notifications from our API in real time. You can configure multiple URLs for the same event, allowing different systems to be notified simultaneously.

The metadata field is optional and can include any custom key-value pairs you want to receive back in your webhook notifications.

Custom Authentication (CUSTOM_AUTH)

When creating a webhook endpoint, you can optionally configure Custom Authentication. This allows our system to dynamically obtain an access token from an external authorization server and include it in every webhook request sent to your endpoint.

To enable this behavior, include the following additional fields in the request body when creating the webhook.

Headers

Name	Value
Authorization	Bearer <token>

Body

Field	Type	Description	Example	Required
url	string	The endpoint URL that will receive webhook events.	"https://example.com/webhook"	yes
description	string	A short description for the webhook endpoint.	"Webhook for PIX and withdrawal events"	no
events	array[string]	A list of event types that will trigger notifications.	["charge.succeeded", "withdrawal.pending"]	yes
metadata	object	Optional field for any custom data you want returned in webhook payloads.	{"myId": "myValue"}	no
authType	string	Defines the authentication strategy used when delivering webhook events	"CUSTOM_AUTH"	no
authConfig	object	Configuration object that describes how the access token should be retrieved and applied to webhook requests	authConfig Object	no

authConfig Object

Field	Type	Description	Example	Required
tokenUrl	string	The URL of the authorization server that will be called to retrieve an access token.	"https://my-endpoint/token"	yes
body	object	Contains credentials and parameters required by the authorization server (for example, OAuth2 Client Credentials)	"client_id": "string", "client_secret": "string", "grant_type": "string"	yes
contentType	string	Specifies the Content-Type header used when requesting the token	"application/json"	no
tokenResponseField	string	Indicates which field in the token response contains the access token.	"access_token"	yes
authorizationPrefix	string	Prefix applied to the token when sending webhook requests.	"Bearer"	yes
additionalHeaders	object	Optional custom headers that will be included when requesting the token and when sending webhook events	{ "Custom-Header": "value" }	no

Available Events

[
    "charge.canceled",
    "charge.created",
    "charge.expired",
    "charge.failed",
    "charge.pending",
    "charge.refunded",
    "charge.succeeded",
    "payment-link.created",
    "payment-link.pending",
    "payment-link.succeeded",
    "payment-link.canceled",
    "payment-link.expired",
    "withdrawal.created",
    "withdrawal.validated",
    "withdrawal.available",
    "withdrawal.pending",
    "withdrawal.succeeded",
    "withdrawal.failed",
    "transaction.created",
    "transaction.succeeded",
    "transaction.pending",
    "transaction.failed",
    "transaction.refunded",
    "transaction.canceled"
  ]

Request Body

Create Webhook EndPoint

{
  "url": "https://example.com/webhook",
  "description": "Webhook for PIX and withdrawal events",
  "events": [
    "charge.succeeded",
    "withdrawal.pending"
  ],
  "metadata": {
    "internalIdentifier": "myValue123"
  }
}

With Custom Auth

Response

200

{
  "metadata": {
    "myId": "myValue"
  },
  "id": "we_01k9ta206722rj53t7jqrc95me",
  "url": "https://example.com/webhook",
  "secret": "{{secret}}",
  "enabled": true,
  "description": "string",
  "createdAt": "2025-11-11T20:34:59.906Z",
  "events": [
    "charge.canceled",
    "charge.created",
    "charge.expired",
    "charge.failed",
    "charge.pending",
    "charge.refunded",
    "charge.succeeded",
    "payment-link.created",
    "payment-link.pending",
    "payment-link.succeeded",
    "payment-link.canceled",
    "payment-link.expired",
    "withdrawal.created",
    "withdrawal.validated",
    "withdrawal.available",
    "withdrawal.pending",
    "withdrawal.succeeded",
    "withdrawal.failed",
    "transaction.created",
    "transaction.succeeded",
    "transaction.pending",
    "transaction.failed",
    "transaction.refunded",
    "transaction.canceled"
  ]
}