Add a webhook

POST 
/api/v8/partner/settings/webhooks

Add a webhook URL and start the verification flow.

When this request is accepted, Veryfi immediately sends a POST request to the provided webhook URL. The verification request body has this shape:

{
  "event": "subscription",
  "data": {
    "secret": "client-specific-secret",
    "created": "2023-05-15 00:00:00"
  }
}

Read the data.secret value from that verification request and send it to the confirm endpoint with the same webhook URL. If the secret matches a pending webhook, Veryfi confirms the webhook and uses it for future notifications.

Restrictions:

• The URL must use HTTPS.
• The URL must be public and accessible from Veryfi.
• Private, local, or loopback URLs are not allowed.
• veryfi.com domains are not allowed.

If Veryfi cannot deliver the initial verification POST, this endpoint returns an error and the webhook is not confirmed.

Request

application/json

Body

url urirequired

Possible values: non-empty and <= 2083 characters

The public HTTPS URL that Veryfi will call to verify the webhook. The URL must be reachable from Veryfi, cannot point to private or local hosts, and cannot use a veryfi.com domain.

Responses

204

Webhook verification request sent. Confirm the webhook with the secret received at your URL.

400

Webhook URL is invalid, prohibited, or the verification request could not be delivered.

application/json

Schema

Schema

any

failed_delivery

Verification POST could not be delivered

{
  "status": "fail",
  "error": "Failed to send webhook subscription request",
  "details": [
    {
      "url": "https://example.com/veryfi/webhook"
    }
  ]
}

malformed_parameters

Malformed or prohibited URL

{
  "status": "fail",
  "error": "Malformed parameters",
  "details": [
    {
      "loc": [
        "url"
      ],
      "msg": "Value error, Webhook URL must be public and accessible from Veryfi",
      "type": "value_error"
    }
  ]
}

Loading...