Webhooks Overview

Webhooks can notify your service about events that happen in an inquiry. See the Events page for a description of supported events.

Webhooks setup

To set up Webhooks, go to Configuration > Webhooks in the Dashboard.

Only enabled events in the specified environment will be sent to your application. You can use a tool like ngrok to test webhooks locally in your sandbox environment.

Responding to events

Webhook events are sent via POST according to the JSONAPI specification.

Affected and related objects are included in the payload attribute. Objects within the payload use the same schema as their API resource endpoints.

Example event from webhook:

{
  "data": {
    "type": "event",
    "id": "evt_XGuYWp7WuDzNxie5z16s7sGJ",
    "attributes": {
      "name": "inquiry.approved",
      "payload": {
        "data": {
          "type": "inquiry"
          "id": "inq_2CVZ4HyVg7qaboXz2PUHknAn",
          "attributes": {
            "status": "approved",
            "reference-id": null,
            "created-at": "2019-09-09T22:40:56.000Z",
            "completed-at": "2019-09-09T22:44:51.000Z",
            "expired-at": null
          },
          "relationships": {
            "reports": {
              "data": []
            },
            "template": {
              "data": {
                "id": "blu_biqYXr3aNfHuLeXUdJUNFNET",
                "type": "template"
              }
            },
            "verifications": {
              "data": [
                {
                  "id": "ver_KnqQRXmxmtquRE65CHTzymhR",
                  "type": "verification/driver-license"
                },
                {
                  "id": "ver_2aguhcwq66zcmqipmrqjxw68",
                  "type": "verification/selfie"
                }
              ]
            }
          },
        },
        "included": [
          {
            "type": "template"
            "id": "blu_biqYXr3aNfHuLeXUdJUNFNET",
            "attributes": {
              "name": "Acme #1"
            },
          },
          {
            "type": "verification/driver-license"
            "id": "ver_KnqQRXmxmtquRE65CHTzymhR",
            "attributes": {
              "status": "passed",
              "front-photo-url": "...",
              "created-at": "2019-09-09T22:41:29.000Z",
              "completed-at": "2019-09-09T22:41:40.000Z",

              ...
            },
          },
          {
            "type": "verification/selfie"
            "id": "ver_2aguhcwq66zcmqipmrqjxw68",
            "attributes": {
              "status": "passed",
              "center-photo-url": "...",
              "left-photo-url": "...",
              "right-photo-url": "...",
              "created-at": "2019-09-09T22:42:43.000Z",
              "completed-at": "2019-09-09T22:42:46.000Z",

              ...
            },
          }
        ]
      }
      "created-at": "2019-09-09T22:46:27.598Z",
    }
  }
}

📘
Including sensitive information in the payload
Due to data privacy requirements and the sensitivity of the data, we allow attributes (e.g. name, birthdate) to be filtered out via blocklist. To view a particular blocklist, visit your Webhooks page and click into a particular webhook to view its configuration.

🚧
Order of received events
The order of your received webhook events may not match the order of our events creation because of various factors like network request latency and exponential retries on failures. Included in the attributes of the request body is the event's created-at timestamp if you need to determine server-side ordering.

Attribute blocklist

Configure a blocklist on the Webhook to prevent certain parts of the webhook payload from getting to your server.

Retry logic

If Persona does not receive a 200 OK from your endpoint within 5 seconds, we will attempt to deliver your webhook up to 8 times with an exponential backoff between attempts (3, 66, 731, 4098, 15627, 46658, 117651, 262146 seconds).

IP addresses

Please see the Security overview page for a list of IPs that webhook requests can originate from.