When a user makes an action in your application, Privy will emit a webhooks payload with the following fields:
Webhook payloads generally have two different formats. Both formats include a user
object that is the same structure as what the user REST API returns. For webhook events that involve an account change, we will include an account
object that represents the changed account. For example, in a user.unlinked_account
event, the account
value will be the account that was just removed, so it will no longer exist on the user
.
Example payload for different webhook events:
The webhook signing key is necessary to verify that the payloads sent to your endpoint are from Privy. Follow the steps below in order to set up webhook verification in your backend.
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.
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
@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:
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.
In order to verify an incoming webhook, please refer to svix’s manual verification guide or library verification guide.
When a user makes an action in your application, Privy will emit a webhooks payload with the following fields:
Webhook payloads generally have two different formats. Both formats include a user
object that is the same structure as what the user REST API returns. For webhook events that involve an account change, we will include an account
object that represents the changed account. For example, in a user.unlinked_account
event, the account
value will be the account that was just removed, so it will no longer exist on the user
.
Example payload for different webhook events:
The webhook signing key is necessary to verify that the payloads sent to your endpoint are from Privy. Follow the steps below in order to set up webhook verification in your backend.
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.
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
@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:
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.
In order to verify an incoming webhook, please refer to svix’s manual verification guide or library verification guide.