📘

## Prerequisites

You have obtained your client_id and client_secret from your Adfin integration manger.

Set up a webhook

Configure a webhook by defining at least one endpoint and a list of events, and you're done. This must be done at least once per app. When you've set up a webhook, Adfin will notify you every time an event occurs for each payment, invoice and direct debit mandate.

Step 1: Expose an endpoint on your server

Set up your own 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

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

Request example:

curl -X POST "https://staging.adfin.com/api/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d '{
    "grant_type": "client_credentials",
    "client_id": "{your_client_id}",
    "client_secret": "{your_client_secret}"
}'

Response example:

{
  "access_token": "your_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response: access_token will expire after 30 mins, use the refresh token endpoint to get a new access token. The token must also be kept a secret and not exposed to any public client.

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

Request example:

curl -X PUT "https://staging.adfin.com/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"
}'

Explanation:

1. URL:

• Replace {client_id} with your actual Adfin client_id.
• Full URL: https://staging.adfin.com/apps/{clientId}/webhooks

2. Authorization header:

• Use the Bearer token from your OAuth 2.0 access token to authenticate the request.

3. Content-Type:

• Set the content type as application/json.

4. Request body:

• url: The URL of your platform's webhook endpoint that will receive the event notifications.
• events: A list of event types to subscribe to, such as payment or dd-mandate.
• name: A human-readable name for the webhook (e.g., Payment Webhook).
• description: A brief description of the webhook's purpose.

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 re-subscribing 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

When an event occurs, Adfin will send a POST request to your registered webhook URL.

Webhook payload example:

{
  "id": "event_id",
  "webhookId": "webhook_id",
  "eventType": "payment",
  "data": {
    "paymentId": "payment_id",
    "paymentDate": "2024-10-21T09:00:00Z",
    "paymentMethod": "credit_card"
  }
}