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 about 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 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 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

 

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 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 amount of HTTP calls the keys can be cached locally for the next day after 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 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.

Types

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:

{
  "partyId":"uuid",
  "externalId":"string",  
  "workflowId":"uuid",
  "workflowStatus":"string",  
  "workflowName":"string",
  "workspaceId":"string"  
}

Field

Description

partyId

Unique identifier of the user

workflowId

Unique identifier of workflow instance

workflowStatus

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

workflowName

Name of your workflow

workspaceId

Unique identifier of your workspace

externalId

Unique Identifier from an external system