Skip to content

Webhook

Boi-das can provide a webhook that sends real-time notifications whenever a validation is accepted or denied within our product. When a validation's status changes, a notification is sent to the URL specified by the client with relevant data.

Webhook Server Requirements

When setting up a webhook endpoint, it's crucial to ensure that your server is properly secured. To do so, it should meet the requirements hereunder.

  • Webhook URL: Ensure you provide a valid URL to receive the webhook notifications.
  • HTTPS Protocol: To ensure a secure and encrypted connection between our system and the customer's system, the URL provided shall use the HTTPS protocol.
  • Authentication: The webhook supports two authentication methods:
    • Legacy Authentication: The URL shall be protected by a basic OAuth authentication mechanism. This verifies the identity of the webhook sender and ensures that only our system can send requests to that URL.
    • OAuth 2.0: The webhook can also authenticate using the OAuth 2.0 protocol. This requires some specific configuration to be compliant with Oauth 2.0 standard.
    • HMAC Signature Authentication: Alternatively, you can use HMAC signature verification for authentication. This method uses cryptographic signatures to verify the authenticity of webhook requests.
  • Availability: The URL shall be available and accessible at all times to ensure timely delivery of webhooks.
  • Supported Formats: JSON.

Also, check out the environment variables required in boi-Das configuration.

Authentication Methods

Legacy Authentication

When using Legacy authentication, clients must provide two endpoints:

  1. Authorization endpoint (/authorize): Used for authentication, where boi-Das sends a request and receives a token in response.
  2. Notification endpoint (/notify): The webhook endpoint that receives notifications using the bearer token.

OAuth 2.0 request headers

  • Token request must include Content-Type: application/x-www-form-urlencoded.
  • Notification request must include Content-Type: application/json.
  • When bearer authentication is enabled, notification request must include Authorization: Bearer <ACCESS_TOKEN>.

OAuth 2.0 token response contract

To ensure OAuth 2.0 compliance, boi-Das expects the token endpoint response to follow these rules:

  • Field names must use snake_case.
  • access_token is required.
  • token_type must be Bearer.
  • Expiration handling (at least one required):
    • expires_in: recommended - number of seconds until expiration
    • issued_at: token creation timestamp in milliseconds
    • Both fields are accepted if provided together
    • Both fields can be provided as JSON numbers (e.g., 3600) or numeric strings (e.g., "3600")

If expiration-related fields (expires_in or issued_at) are missing or cannot be parsed, boi-Das will continue the delivery attempt with the retrieved token but will not cache it for reuse.

HMAC Signature Authentication

When using HMAC signature authentication, clients only need to provide one endpoint:

  1. Notification endpoint (/notify): The webhook endpoint that receives notifications with HMAC signature headers.

With HMAC authentication, boi-Das will send requests with the following headers: - User-Agent: Usually set to "boiDas" - X-Veridas-Signature: Contains the HMAC signature created from a secret defined by the client and the encoded request body using SHA256

The HMAC signature is calculated as: HMAC-SHA256(secret, request_body)

Possible onboarding status

Status Description
pending onboarding is ready to be reviewed
accepted onbording was approved
rejected onboarding was rejected
inconclusive onboarding was set as inconclusive

Webhook Server API

Leveraging boi-Das API

Consider exploring the endpoints explained in the API section of boi-Das documentation to automate webhook requests and verify responses. You will find information on the following:

  • How to query all status change events.
  • How to filter for events where the webhook notification was not sent successfully or not.
  • How to query a specific event
  • How to filter for validations where the webhook notification was not sent successfully or not.
  • How to get all events for a specific validation

Important

In order for the event endpoints to work, the Webhook must be enabled and working. Check out POST /test-webhook endpoint available to check if the webhook is properly set up.