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 | NULLABLE | 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 | NULLABLE | 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"
}
}