Documentation
HomeSupportStatusSign in ->
  • Developer guide
  • How it works?
  • Integration Quick Guide
    • Link Flow
    • Embedded Flow
    • Running Workflow
  • Production setup
  • Webhooks
  • Widget
    • Methods
    • Inline mode
  • Postman Collection
  • Changelog
  • Records
    • Introduction
    • Migration Guide: Migrating from Cases to Records
  • TRANSACTIONLINK API
    • API Reference
      • Authentication
      • Cases (deprecated)
      • Resources
      • Parameters
      • Token
      • Link
      • Workflows
      • Records
        • Attachments
    • API Changelog
    • API Versioning
  • Integrations
    • AIS
      • Data fields availability across banks
      • Testing data
    • Autopay
    • BIG Info Monitor
      • Company Report
      • Personal Report
      • Entrepreneur Report
      • Plus Sco Plus CR3 Report
    • BankID
      • 🇳🇴Norway
      • 🇩🇰Denmark
    • CEIDG
      • Get company
      • List companies
    • Companies House
      • Public Data Api
        • Exemptions
        • Persons with significant Control
        • UK Establishments
        • Filing History
        • Registers
        • Registered Office Address
        • Company Profile
        • Officers
        • Insolvency
        • Charges
      • Documents Api
    • ComplyAdvantage
    • ComplyCube
      • Identity Verification
        • Document Check
        • Proof of Address Check
        • Identity Check
      • Document Check
      • AML Screening Check
      • Face Authentication Check
    • Data Ninja
      • Labeling
      • Profiling
      • Scoring
    • eDO App
    • GUS
    • IAML
    • KRD
      • Company Report
      • Personal Report
      • Identity Card Verification
    • mObywatel
      • CitizenDetails
      • CitizenNationality
    • OnDato
    • Polish VAT Whitelist
    • Przelewy 24
    • PWG
    • QARD
    • Rejestr.io
    • Registru Centras
      • Get company
      • List documents
      • Get document
    • Smart-ID
    • SMS API
    • Twilio
    • MojeId
    • Veriff
      • Supported Browsers
    • VIES (Vat Validation)
      • vies
    • Zoho Sign
      • Adding document fields automatically using text tags
    • Idenfy
    • GBG
      • IDScan
      • Verifications
    • Visa
    • KYB
      • Company Profile
    • Handelsregister
      • Company profile
        • List companies
        • Get company
        • Get company documents
    • InfoCamere
      • Company profile
        • List companies
        • List persons
        • Get company
        • Get person
        • Get documents
    • CBE - Belgium Company Register
      • Company profile
        • List companies
        • Get company
        • List documents
        • Get document
    • Transparenzregister
      • Beneficial owners
        • List companies
        • List documents
        • Get documents
    • CVR (Danish Central Business Register)
      • Company profile
        • List Companies
        • Get Company
        • Get document
    • Malta Business Registry
      • Company profile
        • List Companies
        • Get Company
Powered by GitBook
On this page
  • Get notified about workflow updates
  • Configuring webhooks
  • Security
  • Verification
  • Getting webhook outputs

Was this helpful?

Webhooks

PreviousProduction setupNextWidget

Last updated 1 year ago

Was this helpful?

Get notified about workflow updates

A webhook is a HTTP request used to provide push notifications. TransactionLink sends webhooks to your server to notify programmatically about the completion of the workflow or the change of the workflow status if it is asynchronous.

Our webhooks will notify you of:

  • Workflow completion When the process is completed, we send the information that the workflow is completed for a given user, with the necessary identifiers and the workflow's reference name. After receiving the notification, the data obtained in the process will be available to download via our API.

  • Workflow awaiting The user interaction with widget is finished but some tasks have been being processed in background. When all tasks has been processed there is send workflow completed webhook.

    • Workflow status updates This is especially useful for asynchronous, long-running workflows, which do not respond with an upfront authorization and don't require user input in our widget.

Configuring webhooks

To receive webhooks, set up a dedicated endpoint on your server and then configure the Webhook URL in the "Settings" page of our dashboard. TransactionLink sends POST requests with a raw JSON payload to your designated endpoint.

Test it with ngrok

Webhook retries and connection errors

Unsuccessful or lack of response within ten seconds attempts to notify the client server will be retried up to five times with a five-second interval. Any response outside the 2xx, will result in failure

Security

All outgoing webhooks are signed by TransactionLink. The message signature is included in the JWS-SIGNATURE header in detached format. Verification requires understanding of JSON Web Tokens(JWTs) and JSON Web Signatures.

Verification

Extract the JWT header

After getting the signature from the webhook, you need to extract the JOSE header. It's the part before the first dot. Decode it from base64Url format, and you should get a JSON object like the below.

{
  "alg": "RS256",
  "kid": "070725bf-7dac-4712-b61a-420ba3701263",
  "typ": "JWT"
}

Extract the value corresponding to the kid (key ID) field. This will be used to retrieve the public key corresponding to the private key that was used to sign this request. The alg field specifies the algorithm used for signing. By default it's SHA256 with RSA (RS256)

Get the public key

Validate the signature

To validate the signature you should use a preferred JWT library. The signature is returned in detached format. In order to validate it, the compact format must be composed.

First, the payload in correct format is required. When creating the signature, TransactionLink omits all whitespace in the payload. Remove all whitespace from the payload you received in the webhook and encode it in base64Url. Put the encoded payload into the detached signature (between two dots) to get the compact format.

Having all three required parts you can pass them to a preferred JWS validator and check if the signature is valid.

Getting webhook outputs

You will receive the notifications on your configured webhook endpoint about the workflow. This notification is necessary to retrieve the result of your workflow.

{
  "partyId" : "33e35574-6a97-4e93-94ee-2f28ab3c97c7",
  "caseId" : "33e35574-6a97-4e93-94ee-2f28ab3c97c7",
  "workflowId" : "cd1c4384-bb5b-4483-8974-d8b3ef935843",
  "workflowName" : "70953b16-704a-43a7-b9d0-6cb7d63e491c",
  "workflowDefinitionId" : "a16bc61f-b7ab-4a1d-8301-71740fe6b3a2",
  "workflowStatus" : "COMPLETED",
  "workspaceId" : "aebf8333-5b3e-4840-92dc-f4c8c2c56051"
}

If you don't have a service accessible from a public network to receive data, we can recommend using , which is a reverse proxy fronting web service. Ngrok is the fastest way to put your app on the internet.

Having the kid value ready, you can get the public key by making an API call to TransactionLink API as described . By default, the key is returned in PEM format. Key rotation The key pair used for signing is rotated every 24 hours. After expiration public keys can still be obtained from the API for the next 24 hours. To lower the number of HTTP calls the keys can be cached locally for the next day after the first retrieval.

ngrok
here