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 Authentication:

When using OAuth 2.0 authentication, clients must provide two endpoints:

  1. Token endpoint (/token): Used to obtain an access token following the OAuth 2.0 Client Credentials flow.
  2. Notification endpoint (/notify): The webhook endpoint that receives notifications using the obtained bearer token.

Additional Requirements for OAuth 2.0:

  • All field names in both requests and responses must use snake_case notation.
  • The token response will include either an issued_at field (timestamp when the token was created) or an expires_in field (seconds until token expiration).
  • Token requests must include the Content-Type: application/x-www-form-urlencoded header.
  • Notification requests must include both Content-Type: application/json and Authorization: Bearer [RECEIVED_TOKEN] headers.

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.