Skip to main content

Webhooks

You can configure webhook endpoints via the Multi Portal, so that you are notified about events that apply to your customers, such as card purchases, completions of due diligence processes, transaction state changes, or receipts of deposits.

To use webhook notifications, you need to implement an endpoint that listens to events from Weavr. Weavr will always send webhooks using a POST request with the event details included in the request body.

You can find the full list of published webhooks here.

Configure Your Application Webhook URL​

To start receiving webhooks, you need to switch on webhooks and configure the endpoint to which Weavr will be sending the event details via POST. You can do this in the Multi Portal by navigating to the Settings > Application Details section.

Webhooks configuration

Verify the Authenticity of a Webhook Request​

To verify the authenticity of a webhook notification, generate a local signature and compare the value of the signature-v2 parameter of the received webhook with a local signature.

To generate a local signature, hash the call-ref, message payload and published-timestamp using the HmacSHA256 algorithm with base64 encoding. The call-ref, message payload and published-timestamp should be concatenated in this order without any spaces. The API key will also be required as an input to generate the local signature.

The resultant hashed local signature should match the signature-v2 available in the webhook request header parameters.

note

signature parameter is marked as deprecated and will be replaced by signature-v2 but is still available for backward compatibility. If you are using signature and need to generate a local signature, hash the published-timestamp parameter received in the webhook request together with your API key using the HmacSHA256 algorithm, and then encode the resultant hash using base64 encoding.

Verify the Authenticity of a Webhook Request​

To verify the authenticity of a webhook notification, generate a local signature and compare the value of the signature-v2 parameter of the received webhook with a local signature.

To generate a local signature, hash the call-ref, message payload and published-timestamp using the HmacSHA256 algorithm with base64 encoding. The call-ref, message payload and published-timestamp should be concatenated in this order without any spaces. The API key will also be required as an input to generate the local signature.

The resultant hashed local signature should match the signature-v2 available in the webhook request header parameters.

note

signature parameter is marked as deprecated and will be replaced by signature-v2 but is still available for backward compatibility. If you are using signature and need to generate a local signature, hash the published-timestamp parameter received in the webhook request together with your API key using the HmacSHA256 algorithm, and then encode the resultant hash using base64 encoding.

Webhook Log​

The webhook log will display the below information:

  • Event ID is a unique identifier linked to each webhook event, allowing for tracking and searching of specific events within the Webhook Logs page by searching by the event ID.
  • Created date is the timestamp when the webhook was initially created.
  • Last Sent date is the timestamp when the webhook was last triggered or replayed.
  • Event Type is a categorisation of the type of event that triggered the webhook, such as a login, step-up, a type of transaction or an instrument operation.
  • Operation describes the action associated with the webhook event.
  • The HTTP Code returned by the webhook event in response to the payload delivery attempt, indicating the success or failure of the operation (example 200 for success, 404 for not found, 500 for internal server error).
  • Attempts is the number of times the webhook event was replayed.
  • Status of the webhook if it was successful or not.
note

We restructured the list of webhook events to be presented in descending order, with the latest created event displayed first.

Webhook retries​

Weavr sends webhook notifications as POST HTTP requests on the webhook URL that is specified in the Portal > Application Details.

Whenever an HTTP response error (408,409,425,5xx) is received in response to a webhook request, Weavr will attempt to resend the webhook according to our webhook retry policy. If retries also result in a failure, the webhook is marked as Failed and no further attempts to send the webhook will be made.

Webhook Retry policy​

Weavr will re-attempt to send webhooks to the destination URL with an exponential backoff for 5 times starting with an initial delay of 10 seconds. The delay increments with a factor of 6 after every failed attempt meaning:

  1. Failure on first attempt we will retry after 10s
  2. Failure on second attempt we will retry after 60s (10s *6) i.e. 1 minute
  3. Failure on third attempt we will retry after 360s (60s *6) i.e. 5 minutes
  4. Failure on fourth attempt we will retry after 2160s (360s *6) i.e. 36 minutes
  5. Failure on fifth attempt we will retry after 12960s (2160s *6) i.e. 3 hours 36 minutes
  6. Should the 5th attempt fail, the webhook will be marked as an no further attempt to send the webhook will be made.
tip

Webhook logs can be accessed via the Portal. You can also retry the particular webhook yourself via the Portal.