Trigger BGV Webhook | Gradii API Documentation

Manually trigger a BGV webhook event and dispatch it to all registered webhook URLs subscribed to that event. Useful for re-sending a completed event or testing your webhook integration without re-running the full verification.

Required permissions: bgv:manage.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

eventstringRequired

bgvRequestIdstringOptionalformat: "uuid"

BGV request ID (required if candidateId not provided)

candidateIdstringOptionalformat: "uuid"

Candidate ID (required if bgvRequestId not provided)

campaignIdstringOptionalformat: "uuid"

Campaign ID — optional filter when using candidateId

datamap from strings to anyOptional

Optional custom payload override. If omitted, BGV + DigiLocker details are fetched automatically from the database.

Response

Webhook event dispatched to all registered subscribers

successbooleanOptional

dataobjectOptional

timestampstringOptional

versionstringOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

$	curl -X POST https://gradii.ai/api/v2/webhooks/bgv \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"event": "bgv.completed",
>	"bgvRequestId": "123e4567-e89b-12d3-a456-426614174000"
>	}'

1	{
2	"success": true,
3	"data": {
4	"message": "Webhook event dispatched",
5	"event": "bgv.completed",
6	"bgvRequestId": "123e4567-e89b-12d3-a456-426614174000",
7	"deliveries": {
8	"total": 2,
9	"successful": 2,
10	"failed": 0
11	}
12	},
13	"timestamp": "2024-01-28T10:00:00Z",
14	"version": "2.0"
15	}