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.


Get a platform access token with the client credentials flow, then use it as the Bearer token on every webhooks call below. 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:

POST /apps/{clientId}/webhooks

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

curl -X POST "https://api.staging.adfin.com/api/apps/{clientId}/webhooks" \
-H "Authorization: Bearer your_platform_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 responds with 201 Created and the webhook it created.

{
  "id": "29f6b7ea-94ed-4c3c-9655-b736216c798f",
  "clientId": "{clientId}",
  "url": "https://your-platform/adfin/status",
  "name": "webhook name",
  "description": "webhook description",
  "events": ["payment", "invoice", "dd-mandate"],
  "enabled": true,
  "creationTime": "2025-12-15T10:30:00.000UTC",
  "lastUpdatedTime": "2025-12-15T10:30:00.000UTC"
}

To change a webhook later, use PUT /apps/{clientId}/webhooks/{webhookId}.

Security best practices

  • Rotate secrets periodically: Calling PUT /apps/{clientId}/webhooks/digest again generates a new signing key and returns it. There is no overlap period, and the switch is not instant: webhooks already queued, including retries, were signed with the old key, and some newly sent webhooks can still arrive signed with the old key for a while. Accept signatures from both keys until webhooks signed with the old key stop arriving.
  • 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.
Previous page
Next page