Get notified about workflow updates

A webhook is an 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.

Webhook 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 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 set up webhook in the Integration section in the Dashboard. TransactionLink sends POST requests with a raw JSON payload to your designated endpoint.



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



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.


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

Having the kid value ready, you can get the public key by making an API call to TransactionLink API as described here. 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.

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.


Workflow completion

Workflow completion notifications are triggered when a workflow reaches a final state or is finished with failure.
We also send here information about the step at which the error occurred in case of failure

The example workflow completion notification:





Unique identifier of the user


Unique identifier of workflow instance


Status of workflow. Possible values COMPLETED, FAILED, TIMED_OUT, TERMINATED, PAUSED


Name of your workflow


Unique identifier of your workspace


Unique Identifier from an external system

Did this page help you?