Creating a webhook

1. Navigate to Settings in your Twikey menu
2. Navigate to API
3. Create or click on an existing API key
4. Select the scopes
5. Enter the webhook url (callback address)
6. Press save

Different scopes

Scopes define which webhook events your API key will receive. You can assign different scopes to different keys or endpoints to streamline notifications.

Agreement Scope

This scope covers mandate-related events.

Webhook type: contract

• Includes signing progress, mandate updates, and cancellations.
• Excludes updates of debtor information (e.g., name, address).

Event and State

• Event: Indicates the actual event (e.g., Sign, AcceptedBank, RejectBank)
• State: Represents either the previous or current state of the mandate

Core mandates

• State=SIGNED and Event=Sign indicates the mandate is active.

B2B mandates

• B2B mandates often require bank validation. Example combinations:

Interpretation:

• Event = AcceptedBank → Mandate is active
• Event = Sign and State = SIGNED → Mandate is active
• Event = Sign and State <> SIGNED → Mandate is not active

Payment Scope

This scope covers payment activity events.

• Direct debit
• Credit card transactions
• Payment links

Webhook type: payment

• Webhooks are sent per batch of direct debit transactions, not per individual transaction, to prevent request flooding.
• Payment link webhooks are sent immediately and individually (1:1) and include additional details, such as link expiration.

Customer Scope

Webhook type: customer

Triggered when information of a debtor like name, email, or address is changed.

Other Scope

This includes all other webhook types not covered by the main scopes. The exact events depend on your Twikey configuration and activated features.
See also our API documentation for more information about all other scope types.

Test your webhook

Once activated :

• Click the Test button next to your webhook URL.
• Twikey will send a test request to your server.
• A 2XX HTTP response indicates success; any other response code is treated as a failure.
• You can use the received parameters and headers to verify that your server correctly handles the webhook.

Retry Failed Webhooks

• Webhooks that previously failed can be resent.
• Twikey uses different retry mechanisms depending on the HTTP response received.
• See the Retry Mechanism Documentation for details.
  Important : resending webhooks to an unprepared server may result in request flooding and potential loss of data.

Best practices

• Limit webhook scopes to only the events needed for each endpoint.
• Use HTTPS for webhook URLs to ensure secure communication.
• Validate webhook signatures to confirm authenticity.
• Monitor failed webhooks and investigate promptly to avoid missed events.
• Separate webhooks by environment (production vs. test) to prevent conflicts.