Webhook Best Practices

Respond quickly and process events asynchronously

Persona expects your endpoint to return a successful response (200, 201, 202 or 204) within 5 seconds. If your endpoint responds with an error, or doesn’t respond in time, the delivery counts as failed and Persona retries the webhook event.

We recommend that your webhook handler does as little as possible before it responds:

1. Check the signature of the request.
2. Save the event, or add it to a queue for a background worker to process.
3. Return a 2xx response right away.
4. Do any long-running work in the background worker, after you’ve responded.

A common example of long-running work is downloading files referenced in the payload, such as government ID and selfie images from files.withpersona.com. Other examples are calling other APIs, including the Persona API, or running heavy processing on the event. If your handler does this work before it responds, a slow download can make the request time out. Persona then retries the webhook, and you can end up processing the same event more than once. See Handling duplicate events.

Handling duplicate events

Your webhook endpoints may occasionally receive the same event more than once. This is due to the nature of network connectivity. We recommend making your event processing idempotent to handle duplicate events. One way of doing this is to log events that you’ve processed and to skip processing for already-logged events.

Webhook event ordering

You are not guaranteed to receive webhook events in the order they were created. For example, a network blip may cause an event to be retried and received after a newer event. Please utilize the data.attributes.created-at field to determine creation ordering.

Checking signatures

Requests from webhooks will contain a Persona-Signature header with a hexadecimal-encoded HMAC. You should check that any request is authentic and safe to process by comparing this value with your own digest, computed from the request body and your webhook secret. Your webhook secret can be found in the Webhooks section of the Dashboard.

The Persona-Signature header contains one or more space-separated signature sets. Each set has two comma-separated key-value pairs encoding information about the request. The first key-value pair will be in the form t=<unix_timestamp> and represents the unix time that the request was sent. The second key-value pair will be in the form v1=<signature>, where the signature is computed from your webhook secret and a dot-separated string composed of the unix timestamp joined with the request body.

A webhook usually has one secret, so the header usually has one set: t=<unix_timestamp>,v1=<signature>. While its secrets are rotating, the header contains one set per active secret (see Rotating secrets safely). Always check every v1 signature in the header, and treat the request as authentic if any of them matches.

Sample code for checking signatures:

# The header holds one "t=<timestamp>,v1=<signature>" set per active secret,
# separated by spaces. Check every set and accept the request if any matches.
body = request.body.read
is_verified = request.headers['Persona-Signature'].split(' ').any? do |pair|
  t, v1 = pair.split(',').map { |value| value.split('=', 2).last }
  next false if t.nil? || v1.nil?
  computed_digest = OpenSSL::HMAC.hexdigest('SHA256', <YOUR_WEBHOOK_SECRET>, "#{t}.#{body}")
  Rack::Utils.secure_compare(v1, computed_digest)
end
if is_verified
  # Handle verified webhook event
end

Rotating secrets safely

You can rotate a webhook’s secret in the Dashboard or with the rotate secret API. Rotating creates a new secret. With the API, the old secret stays active for the number of seconds you pass in meta.expires-in-seconds. If you omit it, the old secret expires immediately and there is no overlap.

While both secrets are active, Persona signs every delivery with each of them. The Persona-Signature header then contains one t=<unix_timestamp>,v1=<signature> set per active secret, separated by a space:

t=1764686826,v1=<signature_from_old_secret> t=1764686826,v1=<signature_from_new_secret>

The set for the old secret typically comes first, but don’t rely on the order. Once expires-in-seconds has passed, the old secret expires and the header contains a single set again.

To rotate without rejecting deliveries:

1. Deploy signature checking that accepts the request if any v1 signature in the header matches, like the sample code above.
2. Rotate the secret with an expires-in-seconds long enough to cover your deployment, then save the new secret in your endpoint’s configuration. The API response returns the new secret in secret; it’s also the entry in secrets whose expires-at is null.
3. Let the old secret expire.

CSRF protection

If you’re using Rails, Django, or another web framework, your site might automatically check that every POST request contains a CSRF token. This is an important security feature that helps protect you and your users from cross-site request forgery attempts. However, this security measure might also prevent your site from processing legitimate events. If so, you might need to exempt the webhooks route from CSRF protection.

class PersonaController < ApplicationController
  # If your controller accepts requests other than Persona webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook
  def webhook
    # Process webhook data in `params`
  end
end