Register Webhook
ENDPOINT - https://dominio/api/registerWebhooks/
The Register Webhook endpoint in the ENV Bank allows users to register a new webhook for a specific event, enabling real-time notifications of events such as completed cash-out transactions or charge-related activities. The registered webhook will send event payloads to a specified URL, allowing external applications to react to these events.
🚧 Important!
The secret is used for signing the payload and your end for verifying that the request originates from our API.
When your application receives a webhook call, the request will include a Signature header.
It is STRONGLY ADVISED to validate the signature before taking any action in your application. The signature algorithm employed is SHA256. Refer to the example below for clarification.
✅ It is extremely important that you register all the following Webhook events:
event: ChargeCompleted
event: CashOutCompleted
event: ChargeRefundCompleted
event: CashOutRefunded
Webhook payloads
Below, we have two examples of webhook payloads that our API sends to your application. One for each event, 'CashOutCompleted', 'ChargeCompleted', 'ChargeRefundCompleted' and 'CashOutRefunded'
Pay close attention to the status of the cash-out and the charge, as both the cash-out and the charge may fail.
➡️ Status Explanation
Charge Completed:
PAID: This is the only status possible when a charge is completed successfully.
CashOutCompleted:
DONE (COMPLETED): The payment was made successfully and the customer is notified via webhook.
FAILED: Payment was not made and the transaction was cancelled.
REFUNDED: The cash-out was returned by the customer. Initially, when the cash-out is confirmed, the status is "DONE" and the customer is notified via webhook. If the customer returns the cash-out later, the status is updated to "REFUNDED". In this case, a new webhook is sent with the status updated to "REFUNDED", informing that the cash-out has been refunded.
ChargeRefundCompleted:
REFUNDED: The charge refund event has completed successfully.
Refund Failed: If the refund fails, the charge status remains "PAID". However, in the refunds array, the refund status will be "FAILED".
CashOutRefunded:
The CashOutRefunded webhook is essential for a complete overview of all cash-out refunds, including partial refunds, ensuring that your system is always up to date with the financial situation of each transaction.
Exemplo:
curl --request POST \
--url https://dominio/api/registerWebhooks/ \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data '
{
"event": "ChargeCompleted",
"url": "url-webhook"
}
Resposta 200
{
"success": true,
"action": "created|updated",
"webhook_id": "3",
"message": "Webhook cadastrado|atualizado com sucesso."
}
Resposta 400
{
"error_code": 'RW002',
"reason": "Campo "event" é obrigatório e deve ser "ChargeCompleted", "CashOutCompleted", "ChargeRefundCompleted" ou "CashOutRefunded"."
}
Resposta 400
{
"error_code": 'RW003',
"reason": "Campo 'url' é obrigatório."
}
