General response handling

Each webhook will contain an adfin-webhook-type header, which helps to identify the type of event being processed. You can use this information to build the appropriate logic in your platform to handle each event type effectively. Ensure that you verify the webhook signature to confirm the event’s authenticity before processing it (see Webhook Signature Verification Guide).

1. adfin-webhook-type: invoice

1A. INVOICE_CREATED

Headers

adfin-webhook-id: b5b95480-1c8a-45a2-b9f3-621f927269e6
adfin-webhook-instance-id: d1a25171-48a3-4d55-98a4-c43307d81bd0
x-api-key: %apikey%
adfin-webhook-signature: 6lcr5CWUlHC2pMWL51hRD/wmrRMBtahAswehz42Sfr0=
adfin-webhook-type: invoice
adfin-webhook-signature-timestamp: 2024-11-07T05:04:07.550
content-type: application/json; charset=utf-8

Payload example

{
  "eventId": "3895e973-731f-4fb1-acd8-fae9bd4b4954",
  "type": "INVOICE_CREATED",
  "sourceEntityId": "bcfc401f-c722-4d4c-972b-9ee9212cb8ac",
  "billerId": "b7d2a093-8590-4a99-8c7a-c5d2a1d7a2ed",
  "userId": "8a8dff59-de56-49da-a18b-6816713979e2"
}

1B. INVOICE_ACTIVATED

Headers

adfin-webhook-id: b5b95480-1c8a-45a2-b9f3-621f927269e6
adfin-webhook-instance-id: 2bc90b9b-5317-4c59-9461-4947344c8363
x-api-key: %apikey%
adfin-webhook-signature: +urp4KeJAYHbFw/gBShAUUDsgn9Hxd1GWdrBfUTvbLg=
adfin-webhook-type: invoice
adfin-webhook-signature-timestamp: 2024-11-07T05:02:24.422
content-type: application/json; charset=utf-8

Payload example

{
  "eventId": "5adaaddd-f59b-4327-b3ff-fb08d149e438",
  "type": "INVOICE_ACTIVATED",
  "sourceEntityId": "766401b7-4ea1-4cf9-a429-08709dff2948",
  "billerId": "b7d2a093-8590-4a99-8c7a-c5d2a1d7a2ed",
  "userId": "8a8dff59-de56-49da-a18b-6816713979e2"
}

1C. INVOICE_DELETED

Headers

adfin-webhook-id: b5b95480-1c8a-45a2-b9f3-621f927269e6
adfin-webhook-instance-id: f79d4a83-5936-4ee8-85ce-236defb30838
x-api-key: %apikey%
adfin-webhook-signature: vrTVTh53bZTiWkHQK3yyfE0X9KjGcH+Bjg7TR2+oDUg=
adfin-webhook-type: invoice
adfin-webhook-signature-timestamp: 2024-11-07T05:02:46.252
content-type: application/json; charset=utf-8

Payload example

{
  "type": "INVOICE_DELETED",
  "billerId": "b7d2a093-8590-4a99-8c7a-c5d2a1d7a2ed"
}

2. adfin-webhook-type: dd-mandate

2A. DIRECT_DEBIT_MANDATE_INITIATED

Headers

adfin-webhook-id: fc5a4516-3535-43cd-8cd3-b31148bab58f
adfin-webhook-instance-id: f39c6ebd-4d53-464a-9442-b7b8fa50a721
x-api-key: testApiKey
adfin-webhook-signature: 90EWGEr6QQAfh7alyV1LKXQSyTbHIyyeWX0SAciaBj4=
adfin-webhook-type: dd-mandate
adfin-webhook-signature-timestamp: 2024-11-07T15:13:44.535
content-type: application/json; charset=utf-8

Payload example

{
  "type": "DIRECT_DEBIT_MANDATE_INITIATED",
  "sourceEntityId": "786aca1d-8286-49c5-8a06-3975bd4657d4",
  "billerId": "01782f7d-432c-4b0f-af58-3006f044b706"
}

3. adfin-webhook-type: payment

3A. INVOICE_PAYMENT_MADE

Headers

adfin-webhook-id: fc5a4516-3535-43cd-8cd3-b31148bab58f
adfin-webhook-instance-id: 4891f484-1ade-424d-b18a-5c97f56b67bb
x-api-key: testApiKey
adfin-webhook-signature: GwP0dO8nOg9W0AFf+GZ3ggfbDKin4ZHSoNvMN378zRA=
adfin-webhook-type: payment
adfin-webhook-signature-timestamp: 2024-11-07T15:44:26.039
content-type: application/json; charset=utf-8

Payload example

{
  "eventId": "86707b99-41d9-4722-a036-ee5fcd64f8fb",
  "type": "INVOICE_PAYMENT_MADE",
  "sourceEntityId": "afad4b78-fb4f-4bc3-a7b2-4c0a0a23ce89",
  "billerId": "01782f7d-432c-4b0f-af58-3006f044b706"
}

Security best practices for all events

• Verify signatures: Always verify the webhook signature using the shared secret before processing the event payload.
• Logging: Log incoming webhook events and their responses for audit purposes and troubleshooting.
• Retry mechanism: Implement a retry mechanism in case of webhook delivery failure.