> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.truework.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.truework.com/docs/_mcp/server.

## 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](https://app.truework.com/requester/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:

| Verification method | Webhook recommendation    |
| ------------------- | ------------------------- |
| Instant             | No webhook required       |
| Credentials         | Order completed           |
| Documents (Beta)    | Order completed           |
| Smart Outreach      | Verification state change |

## 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.

**`json_schema`**

```json json_schema
{
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "hook": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "event": {
          "type": "string",
          "enum": ["order.completed"]
        },
        "target": {
          "type": "string"
        }
      }
    },
    "data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        }
      }
    }
  }
}
```

### 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.

**`json_schema`**

```json json_schema
{
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "hook": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "event": {
          "type": "string",
          "enum": ["verification_request.state.change"]
        },
        "target": {
          "type": "string"
        }
      }
    },
    "data": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "pending-approval",
            "processing",
            "action-required",
            "completed",
            "canceled",
            "invalid"
          ]
        },
        "verification_request_id": {
          "type": "string"
        },
        "metadata": {
          "type": "object"
        }
      }
    }
  }
}
```

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](/docs/api-reference/versions/2023-10-30/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](https://app.truework.com/requester/developer-settings) 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.

<Error>Each webhook instance you create is associated with a token. This token is included in all requests made by that webhook. 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 webhook on the developer settings page.</Error>

### Managing webhook subscriptions

Webhooks are managed from your [developer settings page](https://app.truework.com/requester/developer-settings). 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.

<Error>Your webhook handler should ignore any events that it doesn't know how to handle, but still respond with an HTTP 200, before using this functionality. Otherwise adding a subscription may cause errors, webhook retries, and/or failed webhook notifications.</Error>

## Questions?

Reach out to implementations@truework.com.