Guides
Start typing to search…

Webhook events

By subscribing to these webhook events, your platform can stay updated on real-time actions within Adfin and take appropriate actions when a payment is made, a direct debit mandate is signed, or a invoice is created.

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).


adfin-webhook-type: invoice

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: vrTVTh53bZTiWkHQK3yyfE0X9KjGcH+Bjg7TR2+oDUg=
adfin-webhook-type: invoice
adfin-webhook-signature-timestamp: 2024-11-07T05: 02: 24.422
content-type: application/json; charset=utf-8

INVOICE_CREATED

Payload example

{
  "type": "INVOICE_CREATED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "invoiceId": "91279ba0-9a24-4e8f-9c36-b0691e74c72b"
}

INVOICE_ACTIVATED

Payload example

{
  "type": "INVOICE_ACTIVATED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "invoiceId": "6e5e4fdc-4911-4c9b-a3b5-7c4441b43253"
}

INVOICE_DELETED

Payload example

{
  "type": "INVOICE_DELETED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "invoiceId": "2be74caa-3fb7-4dd3-808e-d5f7d51282e9"
}


adfin-webhook-type: dd-mandate

Headers

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

DIRECT_DEBIT_MANDATE_INITIATED


Payload example

{
  "type": "DIRECT_DEBIT_MANDATE_INITIATED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "customerId": "9861c08f-f3a1-4891-9137-254d8b341665",
  "directDebitMandateId": "sqmAMgzyDS8WVyosPo"
}

adfin-webhook-type: payment

Headers

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

PAYMENT_SENT

Payload example

{
  "type": "PAYMENT_SENT",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "paymentId": "60d7b5e5-759d-4af1-9224-ca0082c5f1ad",
  "paymentRequestId": "5c678ac8-b6f1-4e93-ac58-a4664e044023"
}

DD_PAYMENT_FAILED

Payload example

{
  "type": "DD_PAYMENT_FAILED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "customerId": "9861c08f-f3a1-4891-9137-254d8b341665",
  "directDebitMandateId": "60d7b5e5-759d-4af1-9224-ca0082c5f1ad"
}

adfin-webhook-type: customer

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

CUSTOMER_CREATED

Payload example

{
  "type":"CUSTOMER_CREATED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId":"0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId":"08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "customerId":"cbd677d4-bcfa-46b4-be33-26d1d375ebd3"
}

CUSTOMER_UPDATED

Payload example

{
  "type": "CUSTOMER_UPDATED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "customerId": "cbd677d4-bcfa-46b4-be33-26d1d375ebd3"
}

CUSTOMER_DELETED

Payload example

{
  "type": "CUSTOMER_DELETED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "customerId": "cbd677d4-bcfa-46b4-be33-26d1d375ebd3"
}

CUSTOMER_MERGED

Payload example

{
  "type": "CUSTOMER_MERGED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "0bfe8c7e-116c-4c70-abd5-73cba6954f9c",
  "userId": "08b0706f-ca9c-4698-aaa1-2c5e46d8e410",
  "customerId": "cbd677d4-bcfa-46b4-be33-26d1d375ebd3"
}


adfin-webhook-type: biller

BILLER_CREATED

Payload example

{
  "type": "BILLER_CREATED",
  "billerId": "ed0ce9fc-550e-4e2a-af56-7e457dd70dd8"
}

BILLER_PAYMENTS_STATUS_UPDATED

Payload example

{
  "type": "BILLER_PAYMENTS_STATUS_UPDATED",
  "eventId": "965ed90d-afc3-49b3-b60f-7a6eccd100cd",
  "billerId": "ed0ce9fc-550e-4e2a-af56-7e457dd70dd8",
  "userId": "cbd677d4-bcfa-46b4-be33-26d1d375ebd3",
}

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.

Updated 4 months ago

What’s Next