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
credentials_session_tokenstringAssociated credentials session if applicable

Preview#

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

credentials_session.state.change#

Fired when one of your Credential sessions state changes.

Payload#

PARAMETERTYPENULLABLEDESCRIPTION
tokenstringThe token of the credentials session whose state has changed
stateStateThe new state of the credentials session
metadataJSONCustom metadata belonging to the credentials session
verification_request_idstringAssociated verification request if applicable

Preview#

{
"hook": {
"id": "999",
"event": "credentials_session.state.change",
"target": "https://api.your-company.com/webhook"
},
"data": {
"token": "xyz",
"state": "pending"
}
}