post https://api-h.wudi-pay.codesign.ag/api/webhooks
The Register Webhook endpoint in the Wudi Pay 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 aSignatureheader.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.
Below is an example of how to validate the signature:
$signature = hash_hmac('sha256', $responseBodyContents, $secret);
// Then check if the resulting signature is equals to request signature.
// If don't, the request may be fraudulent.
if($signature !== $requestSignature) {
// Throws an exception for possibly fraudulent request
}
import crypto from 'crypto';
// parse payload
function rawBodyParser(jsonString) {
let inQuotes = false;
let str = '';
for (const char of jsonString) {
if (char === '"') {
inQuotes = !inQuotes;
}
if (inQuotes || (char !== ' ' && char !== '\n' && char !== '\r')) {
str += char;
}
}
return str.replace(new RegExp('/', 'g'), '\\/');
}
const signature = req.headers.signature;
const hmac = crypto.createHmac('sha256', webhookSecret);
hmac.update(rawBodyParser(JSON.stringify(req.body)));
const expectedSignature = hmac.digest('hex');
const isValidSignature = signature === expectedSignature;
if (!isValidSignature) {
// Throws an exception for possibly fraudulent request
}
Webhook payloads
Below, we have two examples of webhook payloads that our API sends to your application. One for each event, 'CashOutCompleted' and 'ChargeCompleted'.
Pay close attention to the status of the cash-out and the charge, as both the cash-out and the charge may fail.
Status ExplanationCharge 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".
event: ChargeCompleted
{
"external_id": "2345678...",
"txid": "TX202312031849ZCS4M0LgLIDWP",
"debtor_document_number": null,
"debtor_name": null,
"amount": 20.90,
"status": "PAID",
"payer_request": null,
"additional_information": null,
"qr_code": "00020101021226810014br.gov.bcb.pix2559core.mkbank.com.br/api/cob/46c614f48...",
"qr_code_image_url": "http://image.url/qr_code.png",
"expires_at": "2023-12-03T18:54:06.000000Z",
"paid_at": null,
"account_id": 1,
"updated_at": "2023-12-03T18:49:06.000000Z",
"created_at": "2023-12-03T18:49:06.000000Z",
"id": 1,
"pix_cash_in": {
"id": 1,
"external_id": "49E665D8EFC646B3B3DB6909E960FB9E",
"account_id": 1,
"charge_id": 1,
"end_to_end_id": "E35624319202312041831InaK8WrSy5b",
"amount": 100,
"performed_at": "2023-12-04T18:18:27.000000Z",
"status": "DONE",
"sender_document_number": "00039471697018",
"sender_name": "Fulano de TaskLog",
"transaction_id": "TX202312031849ZCS4M0LgLIDWP",
"initialization_type": "QRDN",
"provider": "IUGU",
"created_at": "2023-12-04T18:18:34.000000Z",
"updated_at": "2023-12-04T18:18:34.000000Z"
}
}
event: CashOutCompleted
{
"id": 1,
"external_id": null,
"uuid": "4530183c-b949-4e0a-affa-1461b967562f",
"end_to_end_id": "E35624319202312041831InaK8WrSy5b",
"amount": 5,
"status": "DONE",
"performed_at": null,
"recipient_account_bank_code": null,
"recipient_account_bank_ispb": null,
"recipient_account_bank_name": null,
"recipient_account_branch": null,
"recipient_account_number": null,
"recipient_account_type": null,
"recipient_document_number": null,
"recipient_name": null,
"initialization_type": "DICT",
"addressing_key": "97592920093",
"addressing_key_type": "CPF",
"provider": "IUGU",
"fee": 0.03,
"correlation_id": "1234567810",
"account_id": 1,
"created_at": "2023-12-04T18:22:15.000000Z",
"updated_at": "2023-12-04T18:22:22.000000Z"
}
event: ChargeRefundCompleted
{
"id": 907202,
"external_id": "28FA75A6EE3441E891950B5677840BCE",
"txid": "LOCALzxcvbnmsdasdasdash123oo3",
"debtor_document_number": null,
"debtor_name": null,
"amount": 59.9,
"status": "REFUNDED",
"payer_request": null,
"additional_information": [],
"qr_code": "00020101021226840014br.gov.bcb.pix2562q...",
"qr_code_image_url": "https://banking.com/qrcode/123456sdfgh234...",
"provider": "IUGU",
"fee": 0.06,
"expires_at": "2023-12-15T18:27:56.000000Z",
"paid_at": "2023-12-15 18:23:24",
"account_id": 1,
"created_at": "2023-12-15T18:22:56.000000Z",
"updated_at": "2023-12-15T18:24:35.000000Z",
"rechecked_at": null,
"refunds": [
{
"id": 4,
"external_id": "28FA75A6EE3441E891950B5677840BCE",
"charge_id": 907202,
"uuid": "52e31f59-3977-4741-b26d-339c1dee1c39",
"end_to_end_id": "D35624319202312152008Krtrm4AEF4b",
"amount": 59.9,
"status": "DONE",
"reason": null,
"performed_at": "2023-12-15T18:23:41.000000Z",
"provider": "IUGU",
"account_id": 1,
"created_at": "2023-12-15T18:23:51.000000Z",
"updated_at": "2023-12-15T18:23:52.000000Z",
"correlation_id": "657ce2684dd28"
}
],
"pix_cash_in": {
"id": 671912,
"external_id": "28FA75A6EE3441E891950B5677840BCE",
"account_id": 1,
"charge_id": 907202,
"end_to_end_id": "E18236120202312151823s01aeecc5b1",
"amount": 59.9,
"performed_at": "2023-12-15T18:23:23.000000Z",
"status": "DONE",
"sender_document_number": "12345678999",
"sender_name": "Sender Name",
"transaction_id": "TXID1234567asdfgh12345",
"initialization_type": "QRDN",
"provider": "IUGU",
"created_at": "2023-12-15T18:23:24.000000Z",
"updated_at": "2023-12-15T18:23:24.000000Z"
}
}
HEADERS
Authorization (string, required): The access token generated by the authentication endpoint must be included in the authorization header in the format Bearer {{access_token}}.
Practical Tips
- Signature Validation: It is strongly recommended to validate the signature of the payload received by the webhook before taking any action in your application. Use the SHA256 algorithm to verify the integrity of received data.
- Monitoring and Maintenance: Maintain an updated list of registered webhooks and regularly monitor incoming notifications to ensure the integrity and correct functioning of integrations.