# Webhook

{% hint style="info" %}
When you create the VX session, set the `webhook.endpoint` value to the HTTPS address that should receive callbacks so status updates are delivered to the correct destination.
{% endhint %}

<mark style="color:green;">`POST`</mark> `[YOUR_ENDPOINT]`

## Payload

{% code lineNumbers="true" %}

```json
{
  "fn": "Avery",
  "ln": "Langley",
  "addr": "742 Evergreen Terrace",
  "city": "Springfield",
  "state": "IL",
  "zip": "62704",
  "dob": "19840224",
  "ssn": "",
  "email": "avery.langley@examplemail.com",
  "phone": "3125550198",
  "reference": "",
  "status": "PENDING",
  "request_id": "e7a5f0d4-1234-5678-9abc-def012345678",
  "additionalData": {
    "customKey": "customValue"
  },
  "dcams_plus": {
    "document_data": {},
    "output": {
      "vpin": {},
      "age_estimate": "",
      "spoof_score": ""
    },
    "api_processing_error": false,
    "service": "PhoneMatch5.0.Smart2FA.SMS",
    "confirmation": 206978022,
    "action": "FAIL",
    "detail": "FAILED OUT-OF-BAND CHECK",
    "issues": []
  },
  "storage": {
    "success": null
  },
  "journey": {
    "stops": [
      {
        "timestamp": "2025-10-04 22:17:55.122089",
        "type": "NEW REGISTRATION",
        "source": "",
        "status": "",
        "action": "",
        "detail": ""
      },
      {
        "timestamp": "2025-10-04 22:18:50.543719",
        "type": "Data Service",
        "source": "PhoneMatch5.0.Smart2FA.SMS",
        "status": "PENDING",
        "action": "PENDING",
        "detail": "MORE INFORMATION IS REQUIRED"
      },
      {
        "timestamp": "2025-10-04 22:19:09.127088",
        "type": "Data Service",
        "source": "PhoneMatch5.0.Smart2FA.SMS",
        "status": "PENDING",
        "action": "FAIL",
        "detail": "FAILED OUT-OF-BAND CHECK"
      }
    ],
    "duration": "00h 01m 14s"
  },
  "documents": null
}
```

{% endcode %}

## Field Reference

The top-level PII fields returned in the webhook payload reflect the most recent values for the user. They represent the latest data either originally provided when creating the session or modified during the journey and echoed back in the webhook.

All `dcams_plus.*` values correspond to the most recent verification transaction.

| Field                             | Type            | Description                                                                                               |
| --------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
| `fn`                              | String          | Latest first name value recorded for the user during the session.                                         |
| `ln`                              | String          | Latest last name value recorded for the user during the session.                                          |
| `addr`                            | String          | Latest street address associated with the user.                                                           |
| `city`                            | String          | Latest city portion of the provided address.                                                              |
| `state`                           | String          | Latest two-character state or province code.                                                              |
| `zip`                             | String          | Latest postal code for the provided address.                                                              |
| `dob`                             | String          | Latest date of birth in `YYYYMMDD` format.                                                                |
| `ssn`                             | String          | Latest Social Security Number value captured (blank in this example).                                     |
| `email`                           | String          | Latest email captured for the verification session.                                                       |
| `phone`                           | String          | Latest primary phone number associated with the user.                                                     |
| `reference`                       | String          | Latest optional value supplied by the client to correlate the session.                                    |
| `status`                          | String          | Overall session status when the webhook fires. Possible values: `PASS`, `FAIL`, or `PENDING`.             |
| `request_id`                      | String          | Session identifier returned when the session was originally created (also referred to as the request ID). |
| `additionalData`                  | Object          | Optional object of client-defined metadata echoed back from the session.                                  |
| `dcams_plus.document_data`        | Object          | Parsed document attributes returned when document checks run.                                             |
| `dcams_plus.output`               | Object          | Additional outputs such as vPIN results, age estimate, and spoof score.                                   |
| `dcams_plus.api_processing_error` | Boolean         | Indicates whether the downstream service returned an error.                                               |
| `dcams_plus.service`              | String          | Name of the service that processed the verification step.                                                 |
| `dcams_plus.confirmation`         | Number          | Confirmation code returned by the downstream service.                                                     |
| `dcams_plus.action`               | String          | Action outcome from the service (for example `PASS`, `FAIL`, or `REVIEW`).                                |
| `dcams_plus.detail`               | String          | Additional detail describing the outcome.                                                                 |
| `dcams_plus.issues`               | Array           | Array of human-readable issues, if any.                                                                   |
| `storage.success`                 | Boolean \| null | Indicates whether the transaction was persisted to long-term storage.                                     |
| `journey.stops`                   | Array           | Chronological list of steps taken within the journey.                                                     |
| `journey.duration`                | String          | Total time elapsed for the journey.                                                                       |
| `documents`                       | Object \| null  | Container for document artifacts when they are returned.                                                  |

## Securing the Webhook

VX supports securing webhook deliveries with either Basic Authentication credentials or an HMAC signature header. Your Veratad representative will work with you to enable the preferred option and share the necessary secrets. Always validate the credential or signature before accepting the payload.