Skip to main content

Webhooks

Webhooks provide a way to listen for events so your integration can automatically trigger reactions.

Why use webhooks

When integrating payment or account information, you might want to perform certain actions on your side, without the need to constantly check on our side.

To enable webhook events, you need to register webhook endpoints and select the appropriate service and environment.

After you register them, Fliqa will push real-time event data to your application’s webhook endpoint.

Webhook events

Webhooks are triggered for the following payment and account information statuses:

Payments​

  • when a payment reaches a final status: successful, canceled, rejected, failed, expired or verification_required

Account information​

  • when a consent is created, expires, or reaches a final status: rejected, valid, revoked_by_psu, expired, terminated_by_tpp or failed

Webhook event payloads

Depending on the selected service, we send a snapshot of the object that changed.

tip

Please make sure that your webhook endpoint can receive the JSON payload, especially if you use the same endpoint for multiple services or event types.

Payment service​

Example of payment payload sent to the webhook endpoint (see Payment JSON for more details):

{
        "paymentId": "78bedd8c832c4685bfba13b5d928bd0b",
        "status": "expired",
        "created": "2023-10-02T07:30:47.736Z",
        "modified": "2023-10-02T10:00:03.350Z",
        "paymentData": null,
        "providerId": "hooked-bank",
        "name": "Demo test transaction",
        "description": "Test open banking transaction",
        "pointOfSaleId": "50d3a8e8-d851-4d5d-a58c-42248ed385a5",
        "sourceIban": null,
        "sourceName": null,
        "targetIban": "SI56263300012039086",
        "targetName": "Top up",
        "amount": 0.01,
        "currency": "EUR",
        "country": "SI",
        "data":
        [
            {
                "key": "customer_id",
                "value": "17cde820-b1df-45ad-98c8-58d26f28abf7"
            }
        ],
        "locale": "en"
}

Account information service​

Example of account information payload sent to the webhook endpoint (see Account Consent JSON for more details):

{
        "inquiryId": "7c6fc32aeda94bdda55109057f07b6ea",
        "consentId": "202411-5NwFXzHwTtKp0oZM5u-JJQ",
        "status": "valid",
        "created": "2024-11-26T08:49:27.887Z",
        "modified": "2024-11-26T08:49:31.067Z",
        "scope": "transactions",
        "validUntil": "2025-05-26T00:00:00.000Z",
        "consentData": null,
        "providerId": "hooked-bank",
        "name": "Retrieve account transactions",
        "description": "Retrieve account transactions",
        "owner":
        {
            "msisdn": null,
            "email": "hook@tester.com"
        },
        "country": "AT",
        "data":
        [
            {
                "key": "customer_id",
                "value": "17cde820-b1df-45ad-98c8-58d26f28abf7"
            }
        ],
        "locale": "en"
}

Best practices

Examine these recommended practices to ensure the security and optimal performance of your webhooks within your integration.

Only listen to events you care about​

Set up your webhook endpoints to exclusively receive the necessary types of events for your integration. Monitoring for additional events (or all events) can place unnecessary stress on your server, and we advise against doing so.

Handle duplicate events​

Webhook endpoints may at times receive duplicate events. To prevent redundant event handling, you can implement idempotence in your event processing. One approach is to log the events you've already processed and avoid reprocessing those that have been logged.

Exclude the webhook route from CSRF protection​

If you're utilizing a framework like Rails, Django, or another web framework, your website might perform automatic checks to ensure that every POST request includes a CSRF token. This serves as a critical security measure to safeguard both you and your users against cross-site request forgery (CSRF) attacks. Nonetheless, this security mechanism could potentially impede the processing of valid events on your site. In such cases, you may find it necessary to exempt the webhook route from CSRF protection.

Ensure HTTPS Server for Receiving Events​

If you specify an HTTPS URL as your webhook endpoint, Fliqa conducts a security check to confirm the secure connection to your server before transmitting webhook data. To enable this, your server must be configured correctly to support HTTPS with a valid server certificate.

Regularly Rotate Endpoint Signing Secrets​

The secret used to verify that events originate from Fliqa can be modified in the webhook details. For each endpoint, you can click 'Regenerate secret'. After regenerating the secret, update verification on your webhook endpoint.

tip

Make sure your webhook endpoint can verify signatures with one or more secrets. Some webhook deliveries may still be signed with the old secret shortly after rotation.

Return a 2xx response immediately​

It is essential that your endpoint promptly delivers a successful status code (2xx) before starting a process that could potentially lead to a timeout.

Webhook verification

It is especially important to verify that Fliqa generated a webhook request and that it didn’t come from a server acting like Fliqa.

Signature​

The webhook POST request will contain a X-Fliqa-Signature header in the following format:

t=1696242888,v=1e49bf8db353a19c3924822601452a7aacfd4f24487b7d4568bc9c5f9ac7386b

Alternatively if a new secret was regenerated within the last 24 hours:

t=1696242888,v=1e49bf8db353a19c3924822601452a7aacfd4f24487b7d4568bc9c5f9ac7386b,v0=f8f9c3507c01c2582241ca1b70c93aebea808757be800afbf374aeb402d4a101

where:

  • t = epoch timestamp in seconds: when the webhook signature was created to prevent replay attacks
  • v = the signature calculated from the secret, timestamp, webhook URL, and request body (JSON payload)
  • v0 = the signature calculated using the previous secret, if the secret was regenerated within the last 24 hours

Refer to: Webhook signature verification for implementation details!