Webhooks

Rather than polling the Truework API for changes, you can arrange for us to send a POST request to a URL you provide whenever certain events occur.

There are a few important things to note:

Truework will only send webhook requests over HTTPS.
Each webhook instance you create is associated with a token. This token is included in all requests made by that hook.
Tokens can be retrieved from the webhooks section of your API settings.
You should check the X-Truework-Token header included with each webhook request and reject any request whose token does not correspond to the one shown for that hook on the settings page.

Anatomy of a Webhook#

Webhook requests always have the following fields:

PARAMETER	TYPE	NULLABLE	DESCRIPTION
hook	`Hook`		Metadata about the webhook
data	[many]		A payload specific to the event type

`Hook`#

PARAMETER	TYPE	DESCRIPTION
id	string	The `id` of the hook itself. You may have several hooks keyed off of the same event
event	string	A unique string which identifies the event which triggered this hook
target	string	The URL to which the hook's payload is sent

Available Webhooks#

`verification_request.state.change`#

Fired when one of your Verification requests changes.

Payload#

PARAMETER	TYPE	DESCRIPTION
verification_request_id	string	The `id` of the verification request whose state has changed
state	`State`	The new state of the verification request
metadata	JSON	Custom metadata belonging to the verification request

Preview#

{
  "hook": {
    "id": "999",
    "event": "verification_request.state.change",
    "target": "https://api.your-company.com/webhook"
  },
  "data": {
    "verification_request_id": "123",
    "state": "completed"
  }
}