Skip to main content

API hooks

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

Why to 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.

Hook events

Are triggered on following payment/account information statuses

Payments service​

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

Account information​

  • When consent was created, has expired or reached a final status: rejected, valid, revoked_by_psu, expired, terminated_by_tpp or failed

Hook event data

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

tip

Please make sure that your hook endpoint is capable of receiving the JSON payload. Especially if you are using the same hook endpoint for various services/events

Payment service​

Example of payment payload sent to hook 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 hook 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 listed 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 for verify that events originate from Fliqa can be modified within the Webhooks details. For each endpoint, you can click 'Regenerate secret.', after that you need to adjust your hook endpoints verification.

tip

Make sure your hook endpoint can check hook verification with one or more secrets. It might be that some hook events will be delivered with the old verification.

Return a 2xx response immediately​

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

Hook 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 hook POST request will contain a X-Fliqa-Signature header in the following format:

t=1696242888,v=1e49bf8db353a19c3924822601452a7aacfd4f24487b7d4568bc9c5f9ac7386b

or alternatively in case a new secret was regenerated withing 24 hours

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

where:

  • t = epoch timestamp in seconds: when hook signature was created to prevent replay attacks
  • v = the verification signature that is calculated from the secret, timestamp, hookUrl and body (JSON payload)
  • v0 = the old verification signature calculated from the old secret if secret was regenerated altered in the last 24 hours

Refer to: Hook signature verification for implementation details!