Skip to content

Webhooks

Introduction

Webhooks allow your application to receive real-time notifications from Finrelay whenever specific events occur. Instead of polling APIs, you can set up a webhook endpoint to automatically receive updates when important activities happen.

Webhooks enable event-driven workflows, such as transaction status updates or system notifications, without the need for manual polling.

How Webhooks Work

When an event occurs (for example, a transaction is processed), Finrelay sends an HTTP POST request to your registered webhook URL. The request contains a JSON payload describing the event.

Each webhook request is signed using JWT (JSON Web Token) for security and integrity verification.

You must set up an endpoint on your server to receive, validate, and process these webhook notifications.

Configuring Webhooks

Currently, webhook configuration is not self-service.\ To configure webhook delivery for your account:

  1. Contact the Finrelay Support Team.
  2. Provide your webhook endpoint URL and any environment-specific details.
  3. Our team will configure your webhook subscriptions on your behalf.

Support contact information is available through your client portal or support@finrelay.com.

Security and Signature Verification

Every webhook request from Finrelay includes a JWT token in the Authorization header.\ The JWT is signed and must be verified to ensure the authenticity of the webhook.

Signature details:

  • The JWT payload contains a data claim:

    {
  "SHA512": "<digest-value>"
}
    * The <digest-value> is a SHA-512 hash digest of the webhook request body. * The webhook request body must be hashed using SHA-512, and the resulting digest must match the one in the JWT payload. * The JWT must also be cryptographically verified using the correct public key.

Important:

  • Depending on the event type, different private keys are used for signing.
  • For transaction-related events, the merchant's private key is used.
  • Always refer to the event-specific documentation for details about which key applies.

Delivery and Retry Policy

  • If your webhook endpoint responds with a 2xx HTTP status code, the delivery is considered successful.
  • If your endpoint returns a 4xx/5xx error or times out, Finrelay retries the webhook with exponential backoff.
  • Retry attempts continue for up to 24 hours.
  • After the retry window expires without success, the event is marked as undeliverable.

Ensure that your webhook endpoint:

  • Is highly available.
  • Quickly responds to POST requests (recommended within 2 seconds).

Best Practices

  • Always verify the JWT signature and the SHA-512 digest before processing the event.
  • Log webhook payloads and headers for audit and troubleshooting purposes.
  • Implement idempotency to safely handle duplicate webhook deliveries.
  • Respond with an HTTP 2xx status as quickly as possible.
  • Secure your webhook endpoints with HTTPS.

JWT Signature Verification – Flow Description

When your server receives a webhook request from Finrelay, you must:

  1. Extract the Authorization header (which contains the JWT).
  2. Split authorization header on two parts (Bearer and token)
  3. Decode the JWT header and payload (without verifying yet).
  4. Retrieve the "data" claim from the JWT payload, which contains the SHA-512 digest of the request body.
  5. Hash the received request body yourself using SHA-512.
  6. Compare your calculated hash to the SHA512 value inside the data claim.
  7. Verify the JWT's signature using the correct public key.
  8. For transaction events: use the merchant’s public key.
  9. (Other events may use different keys; see event-specific documentation.)
  10. If the digest matches and the signature is valid → accept the webhook.

If any of these steps fail → reject the webhook (return 401 Unauthorized).

flowchart TD
    A[Receive Webhook Request] --> B[Extract Authorization Header JWT]
    B --> C[Decode JWT Header and Payload]
    C --> D[Extract 'data' Claim SHA512 Digest]
    C --> E[Extract Public Key based on Event Type]
    A --> F[Hash the Request Body using SHA-512]
    D --> G{Compare Digest Values}
    F --> G
    G -- Match --> H{Verify JWT Signature}
    G -- Mismatch --> X[Reject Webhook 401 Unauthorized]
    H -- Valid --> Y[Accept Webhook and Process Event]
    H -- Invalid --> X

Summary

  • The digest comparison ensures payload integrity (body wasn't tampered).
  • The JWT signature ensures origin authenticity (Finrelay sent it, not someone else).
  • Both must pass.