Webhooks

Setting up webhooks for your Truework API integration

Truework uses webhooks to asynchronously update our partners when a verification completes. Webhooks can be configured from the Developer Settings in the Truework app. There are two types of webhooks: Order completed and Verification state change.

Webhooks can be used as an indicator to act on certain events that occur while Truework is processing a verification. Once configured, Truework will make a POST request to a specified HTTPS endpoint to notify you when an event 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.

Of interest will mostly be the states completed and canceled. A completed state indicates that new data is now available on the order. A canceled state indicates that a verification was not able to be completed, but may have user-provided information and/or documents.

Truework will retry failed webhooks periodically over a period of 48 hours. You will receive notifications to your service account email for any webhooks that fail to send.

Webhook recommendations

Based on the verification method(s) you are using, we recommend using the following webhooks:

Webhook subscriptions

Order completed webhook

Order completed

The order.completed webhook will be issued when all verifications associated with the order have been completed or canceled. Once you receive this webhook you can fetch the order results from the API.

1
{
2
  "type": "object",
3
  "properties": {
4
    "version": {
5
      "type": "string"
6
    },
7
    "hook": {
8
      "type": "object",
9
      "properties": {
10
        "id": {
11
          "type": "integer"
12
        },
13
        "event": {
14
          "type": "string",
15
          "enum": ["order.completed"]
16
        },
17
        "target": {
18
          "type": "string"
19
        }
20
      }
21
    },
22
    "data": {
23
      "type": "object",
24
      "properties": {
25
        "order_id": {
26
          "type": "string"
27
        }
28
      }
29
    }
30
  }
31
}

Verification state change webhook

If you need more granular updates about the data contained within an order for Smart Outreach, you can additionally and/or alternatively listen to this webhook, which is issued when a verification request within the order changes state. Of interest will mostly be the states completed and canceled. A completed state indicates that new data is now available on the order. A canceled state indicates that a verification was not able to be completed, but may have applicant-provided information and/or documents.

1
{
2
  "type": "object",
3
  "properties": {
4
    "version": {
5
      "type": "string"
6
    },
7
    "hook": {
8
      "type": "object",
9
      "properties": {
10
        "id": {
11
          "type": "integer"
12
        },
13
        "event": {
14
          "type": "string",
15
          "enum": ["verification_request.state.change"]
16
        },
17
        "target": {
18
          "type": "string"
19
        }
20
      }
21
    },
22
    "data": {
23
      "type": "object",
24
      "properties": {
25
        "order_id": {
26
          "type": "string"
27
        },
28
        "state": {
29
          "type": "string",
30
          "enum": [
31
            "pending-approval",
32
            "processing",
33
            "action-required",
34
            "completed",
35
            "canceled",
36
            "invalid"
37
          ]
38
        },
39
        "verification_request_id": {
40
          "type": "string"
41
        },
42
        "metadata": {
43
          "type": "object"
44
        }
45
      }
46
    }
47
  }
48
}

If a verification reaches Smart Outreach, it can hit an action-required state, indicating that more information is required to process the request. Additional information can be submitted via your Truework account in the app. If you do not wish to have your internal users login to Truework to understand what action is required, you can set up your integration to Cancel an order if an action-required state is received.

Creating and managing webhook subscriptions

Creating a webhook subscription

To create a webhook, go to the developer settings page in your service account, and navigate to “< > Developer” from the left hand panel. Then scroll down to Webhooks > “Sandbox” or “Production” (depending on the environment you are generating the API keys for) and click “Edit” to get started.

Webhooks support subscribing to multiple event types. Select the desired webhook from the subscriptions dropdown, enter the URL where the webhook should be sent, and optionally create a description to differentiate this webhook from others. Click “Create” to configure the webhook.

There is a limit to ten (10) webhooks total per service account. Webhook handlers should be idempotent, as it is possible for a given webhook event to be sent more than once.

Managing webhook subscriptions

Webhooks are managed from your developer settings page. Navigate to “< > Developer” from the left hand panel. Then scroll down to Webhooks > “Sandbox” or “Production” and click “Edit”. You can add, unsubscribe, and delete webhooks at any time. 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.

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.

Questions?

Reach out to implementations@truework.com.