Skip to content
Last updated

Configure webhooks

Configure a webhook by defining at least one endpoint and a list of events, and you're done. When you've set up a webhook, Adfin will notify you every time an event occurs for the object.

Prerequisites

To proceed with this guide, you must have completed your webhook signature verification Webhook Signature Verification

1. Expose an endpoint on your server

Set up your endpoint to receive notifications. The endpoint should be a publicly accessible URL that can receive POST requests from Adfin. The event payload is sent in the request body.

Endpoint example: https://your-platform.com/webhook-endpoint

2. Generate a client access token

Make sure you're using the correct access token type

To use our webhooks API, generate an access token using the client credentials flow. You will receive an error if using an access token generated during the authorization code flow.


Follow the instructions in this section to authorise access to your backend client. Remember that your client_secret should be kept a secret: only use it to authenticate with the Adfin platform and don’t share it outside your organisation.


3. Subscribe to webhooks

Webhook subscription endpoint:

PUT /apps/{client_id}/webhooks

This endpoint allows you to subscribe your platform to specific events from Adfin (e.g., payment, dd-mandate).

curl -X PUT "https://api.staging.adfin.com/api/apps/{client_id}/webhooks" \
-H "Authorization: Bearer your_access_token" \
-H "Content-Type: application/json" \
-d '{
    "url": "https://your-platform/adfin/status",
    "events": ["payment", "invoice", "dd-mandate"],
    "name": "webhook name",
    "description": "webhook description"
}'

This cURL request will register your platform to receive webhook events, which can be used to handle real-time updates from Adfin (like payments being made or mandates being signed)​

Response example:

If the request is successful, Adfin will respond with a confirmation that the webhook has been created.

{
  "id": "29f6b7ea-94ed-4c3c-9655-b736216c798f",
  "url": "https://your-platform/adfin/status",
  "events": ["payment", "invoice", "dd-mandate"],
  "name": "webhook name",
  "description": "webhook description",
  "enabled": true
}

Security best practices

  • Rotate secrets periodically: If needed, rotate the shared secret by resubscribing to the webhook.
  • Rate limiting: Apply rate limits to your webhook endpoints to prevent abuse.
  • Logging: Log all webhook verification failures and investigate unusual patterns of failed verification attempts.

Webhook payload

To view the webhook payloads, please use our Webhook events page Webhook events

Previous page
Next page