Skip to main content

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.
Configuring a Webhook

For instructions on how to configure a webhook, see Configuring a Webhook

Anatomy of a Webhook#

Webhook requests always have the following fields:

PARAMETERTYPENULLABLEDESCRIPTION
hookHookMetadata about the webhook
data[many]A payload specific to the event type

Hook#

PARAMETERTYPENULLABLEDESCRIPTION
idstringThe id of the hook itself. You may have several hooks keyed off of the same event
eventstringA unique string which identifies the event which triggered this hook
targetstringThe URL to which the hook's payload is sent

Available Webhooks#

verification_request.state.change#

Fired when one of your Verification requests changes.

Payload#

PARAMETERTYPENULLABLEDESCRIPTION
verification_request_idstringThe id of the verification request whose state has changed
stateStateThe new state of the verification request
metadataJSONCustom 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"
}
}