Configuration and operation of Webhooks🚧

This article covers the configuration and operation of Webhooks for Pix events.

Webhook Configuration

The webhook configuration endpoint (PUT /webhook/{key}) is used to register the URL that will receive Pix event notifications. This process is synchronous, as the response to the request is immediate, confirming that the webhook has been correctly configured or informing about possible errors.

Request

PUT /webhook/{key}
Host: api.example.com
Content-Type: application/json

{
  "webhookUrl": "https://pix.example.com/api/webhook/"
}

 

Response

{  
  "webhookUrl": "<https://pix.exemplo.com/api/webhook/">,  
  "chave": "40a0932d-1918-4eee-845d-35a2da1690dc",  
  "criacao": "2020-11-11T10:15:00.358Z"  
}

PUT /webhook/{chave} endpoint returns immediately, confirming the success or failure of the configuration.

How Webhooks Work

The nature of webhooks is asynchronous. Once the webhook is configured, the Pix API will send event notifications to the configured endpoint whenever those events occur. The notifications are sent asynchronously, as the call to the webhook happens at a future time, in response to a specific event (such as receiving a Pix payment).

Example Webhook Notification:

Example

{  
  "txid": "1234567890",  
  "endToEndId": "E1234567890123456789012345678901",  
  "valor": "100.00",  
  "horario": "2021-12-25T12:34:56.789Z",  
  "infoPagador": "Pagamento referente à fatura 1234"  
}

Notifications are sent later in response to specific events, without an immediate wait from the client.

Note:

This article focuses exclusively on the configuration and operation of webhooks for cash-in transactions. However, it is important to note that cash-out scenarios are addressed separately in the document "Response Payload Scenarios for Webhooks".