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 (/verification/{verificationId}/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.

Note: You can also define a webook in the Program Settings page.