DocumentationAPI Reference
DocumentationAPI Reference

Webhooks can notify your service about events that happen in an inquiryinquiry - A single instance of an individual attempting to verify their identity.. See the Events page for a description of supported events.

Webhooks setup

To set up Webhooks, go to Configuration > Webhooks in the DashboardDashboard - A hub for organizations to review inquiries and manage their integration with Persona..

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 sandboxsandbox - A mode that allows you to test using sample data. 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",
    }
  }
}

Your endpoint must return an 200 OK. If Persona does not receive an 200 OK from your application, it will retry until it is received, up to a maximum of 8 times.

📘

Including PII in the payload

Due to data privacy requirements and the sensitivity of the data, we do not expose the PII collected through the verification process by default. Based on your needs and how you plan to use the PII, we allow selected attributes (e.g. name) to be accessed via API.

🚧

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.

Retry logic

If Persona does not receive a 200 OK from your endpoint, 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

All webhook requests will come from the following IPs.

  • 35.232.44.140
  • 34.69.131.123
  • 34.67.4.225