Webhook¶
vali-Das can provide a webhook that sends real-time notifications whenever a validation changes status 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.
- OAuth Authentication: The URL shall be protected by an OAuth authentication mechanism. This verifies the identity of the webhook sender and ensures that only our system can send requests to that URL.
- Availability: The URL shall be available and accessible at all times to ensure timely delivery of webhooks.
- Supported Formats: JSON.
Possible validation status¶
| Status | Description |
|---|---|
| on-course | validation has been created |
| document-uploaded | validation has Score-DocumentGlobal score |
| document2-uploaded | validation has Score-DocumentGlobal score |
| document3-uploaded | validation has Score-DocumentGlobal score |
| selfie-uploaded | validation has ValidasScoreSelfie |
| video-uploaded | validation has ValidasScoreVideo |
| cancelled | validation cancelled with PUT /validation/validation_id/cancellation endpoint |
| confirmed | validation confirmed with PUT /validation/validation_id/confirmation endpoint |
| deleted | validation deleted with DELETE /validation/validation_id endpoint |
| scores-computed | device integrity scores calculated with PUT /process-information/validation_id endpoint |
Authentication Methods¶
Basic OAuth Authentication¶
When using OAuth authentication, clients must provide two endpoints:
- Authorization endpoint (/authorize): Used for authentication, where vali-Das sends a request and receives a token in response.
- Notification endpoint (/notify): The webhook endpoint that receives notifications using the bearer token.
OAuth 2.0 Authentication¶
When using OAuth 2.0 authentication, the endpoints are the same as in the basic OAuth authentication and to enable the OAuth 2.0 mode these parameters must be set as follow:
| Parameter | Type | Default | Value |
|---|---|---|---|
use_bearer_auth |
boolean |
false |
true |
content_type |
string |
empty | x-www-form-urlencoded |
Whe this mode is activated, the requests to the /notify endpoint will include the Authorization: Bearer <token> header in all outgoing notification requests.
Verification¶
You can verify the configuration by performing a GET /validas/v1/webhook/test. The response will include the use_bearer_auth status.
Webhook Server API¶
Leveraging vali-Das API¶
Consider exploring the endpoints explained in the API section of vali-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
Please read carefully
- In order for the event endpoints to work, the Webhook must be enabled and working. Check out
POST /test endpointavailable to check if the webhook is properly set up.
Steps to follow¶
1. Call POST /validas/v1/webhook/settings to create the webhook settings
2. Verify that settings have been successfully created on step 1 by calling GET /validas/v1/webhook/settings
3. Check that the created webhook works using POST /validas/v1/webhook/test