Verifying a webhook payload

Webhook payloads must be verified before they are trusted and used on your server. This is done by verifying a signature sent with your webhook. Privy uses svix for webhooks infrastructure.

TIP

Your endpoint must return a 2xx (status code 200-299) response for the webhook to be marked as delivered. Any other statuses (including 3xx) are considered failed deliveries. Your endpoint will be automatically disabled after 5 consecutive days of delivery failures

Using @privy-io/server-auth

Use the PrivyClient's verifyWebhook method to verify an incoming webhook. Pass in the request body, headers, and signing key (from the Privy Dashboard). As an example, for a NextJS API request, you can verify a webhook using the code below:

// req is an input of type `NextApiRequest`

const privy = new PrivyClient(
  process.env.PRIVY_APP_ID as string,
  process.env.PRIVY_APP_SECRET as string,
);

// Get the request's `id`, `timestamp`, and `signature`
// These are sent in the `'svix-id'`, `'svix-timestamp'`, and `'svix-signature'` headers respectively
const id = req.headers['svix-id'] ?? '';
const timestamp = req.headers['svix-timestamp'] ?? '';
const signature = req.headers['svix-signature'] ?? '';

const verifiedPayload = await privy.verifyWebhook(
  req.body,
  {id, timestamp, signature},
  'insert-your-webhook-signing-key-from-the-dashboard',
);

If the webhook payload is valid, the method will return the payload back. If the webhook payload is invalid, the method will throw an error.

Manual verification

In order to verify an incoming webhook, please refer to svix's manual verification guide or library verification guide.