Webhooks | Truework Docs

Webhooks can be used to act on certain events that occur while Truework is processing your verifications. Once configured, Truework will make a POST request to a specified HTTPS endpoint to notify you when those events occur.

As verifications get processed, they pass through a number of states. Each time a state transition occurs, Truework can generate a webhook to notify you of the new state. This can be used to trigger any processing that depends on the verification having reached a certain state.

There is a limit to ten (10) webhooks total. Webhook handlers should be idempotent as is possible for us send the same webhook event multiple times.

We will retry failed webhooks periodically over a period of 48 hours. You will receive notifications by email for any webhooks that fail to send.

Creating a webhook

To create webhook, navigate to your developer settings page. Under the “API ” header find the “Production” card, and expand the webhook section by clicking the “Edit” button. Then, select the desired events from the subscriptions dropdown, enter the URL where the webhook should be sent, and optionally a description to differentiate this webhook from others. Click “Create” to configure the webhook.

Webhook subscriptions

Webhooks support subscribing to multiple event types. You can add and remove subscriptions in the webhooks panel, above the creation form.

Your webhook handler should ignore any events that it doesn’t know how to handle, but still respond with an HTTP 200, before using this functionality. Otherwise adding a subscription may cause errors, webhook retries, and/or failed webhook notifications.

Subscription versioning

Subscriptions are made to specific versions of each event. The version of a subscription can be upgraded, but cannot be downgraded. Additionally, new subscriptions may only be made to the latest version. The only field that is sure to be consistent across versions is the top-level version field.

Deleting a webhook

To delete a webhook, simply press the “Delete” button next to the webhook you wish to delete in the developer settings page. Ensure any webhook you delete is not in use, as you can create a new webhook with the same URL, but the token value will differ.

Sandbox webhooks

To create or delete webhooks in the sandbox environment, find the “Sandbox” card and follow the above instructions. You can use a webhook logger like Webhook.site to inspect the webhook payload.

Webhook events

You can find a current list of webhook events and their payloads in the API reference.