Creating Webhooks
In this guide, we’ll go through the necessary steps to create a webhook for any verifications done on your program. The end result is a call from SheerID’s service to an endpoint of your choice when any verification becomes successful.
Overview
Webhooks are used to notify you about successful verifications so you can continue moving users through
your workflow. When combined with the details GET request they allow you to do things like receive the reward code for that verification and pass it along to the user.
Set up a Webhook
Use the webhook POST request to configure your webhook URI for your program. Follow the schema in the following example, creating a webhook at http://example.com:
Request:
POST /rest/v2/program/<YOUR_PROGRAM_ID>/webhook HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>
{
"callbackUri": "http://example.com"
}
A successful request will return a 200 OK response, and your program is now configured to pass
verification IDs to your webhook.
HTTP/1.1 200 OK
Content-Type: application/json
Request Parameters
callbackUri: string, The URI for your configured webhook.
Retrieve Verification Details
Now that your program is configured with your webhook, SheerID will pass the verificationId to
the webhook upon a successful verification:
{
"verificationId": "the verification id"
}
Use the Verification Details endpoint to monitor the status of the verification, keep track of steps, provide the reward code to end users, etc.
Remove and Change a Webhook
Once a webhook is set on a program you may not use the webhooks POST request to change it. Doing so will result in a 409 Conflict error code, indicating that the webhook already exists.
Use the webhook DELETE request to remove it.
DELETE /rest/v2/program/<YOUR_PROGRAM_ID>/webhook HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>
{
"callbackUri": "http://example.com"
}
Once deleted you can add an updated webhook by using the webhook POST request again.