Webhooks overview

Webhooks allow you to specify a backend endpoint that Privy will call with a signed payload whenever a user makes an action in your application, such as logging in, or linking a new account. As soon as you register an endpoint, Privy will start sending subscribed events in near real-time.

Webhooks can be tested at no cost in development environments. To enable webhooks in production, upgrade to the Enterprise plan in the Privy Dashboard.

Registering an endpoint

In your backend, create a new endpoint that will accept POST requests from Privy
When creating your endpoint to receive webhook events, always verify the payload signature by following our webhook signing key documentation.
In the dashboard, go to the Configuration > Webhooks page
Add your new endpoint as the destination URL and select any event types you’d like to be notified for. The URL must begin with https://.

You can specify which user events your webhook endpoint will be notified about. The options are as follows:

Event Name	Type	Action
User created	user.created	A user was created in the application.
User authenticated	user.authenticated	A user successfully logged into the application.
User linked account	user.linked_account	A user successfully linked a new login method.
User unlinked account	user.unlinked_account	A user successfully unlinked an existing login method.
User updated account	user.updated_account	A user successfully updates the email or phone number linked to their account.
User transferred account	user.transferred_account	A user successfully transferred their account to a new account.
Wallet created for user	user.wallet_created	A wallet (embedded or smart wallet) was successfully created for a user.
MFA enabled	mfa.enabled	A user has enabled MFA for their account.
MFA disabled	mfa.disabled	A user has disabled MFA for their account.
Private key exported	private_key.exported	A user has exported their private key from an embedded wallet.
Wallet recovery setup	wallet.recovery_setup	A user has set up wallet recovery for their embedded wallet.
Wallet recovered	wallet.recovered	A user has successfully recovered their embedded wallet.
Intent created	intent.created	An intent was proposed and is awaiting approval.
Intent authorized	intent.authorized	A team member authorized an intent.
Intent executed	intent.executed	An intent was fully approved and the action completed successfully.
Intent failed	intent.failed	An intent was fully approved but the action failed during execution.
User operation completed	user_operation.completed	An ERC-4337 UserOperation landed on-chain.

That’s it! You’ve successfully configured webhooks for your app. 🎉

Testing the webhook setup

Quick testing guide

During development and testing, you can quickly verify your webhook endpoint is working correctly. Here’s a simple step-by-step guide:

Step 1: Expose your local endpoint

If you’re testing locally, you’ll need to expose your local server to the internet. Use a tool like ngrok or Cloudflare Tunnel:

# Using ngrok (after installing: https://ngrok.com/download)
ngrok http 3000

# Or using Cloudflare Tunnel (after installing: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/)
cloudflared tunnel --url http://localhost:3000

Copy the public URL (e.g., https://abc123.ngrok.io or https://abc123.trycloudflare.com).

Step 2: Create your webhook endpoint

Create a simple endpoint in your backend that accepts POST requests:

import {NextRequest, NextResponse} from 'next/server';

export async function POST(req: NextRequest) {
  const body = await req.json();

  // Log the webhook payload
  console.log('Webhook received:', body);

  // Return 200 to acknowledge receipt
  return NextResponse.json({received: true}, {status: 200});
}

Step 3: Register your endpoint in the dashboard

Go to Configuration > Webhooks in the Privy Dashboard
Add your public URL (from Step 1) as the webhook endpoint
Select the event types you want to test

Step 4: Test your endpoint

Click the “Test webhook” button in the dashboard. This will send a test webhook (privy.test) to your endpoint with the following payload:

{
  "type": "privy.test",
  "message": "Hello, World!"
}

Step 5: Verify receipt

Check your server logs to confirm you received the webhook. You should see:

The webhook payload in your console/logs
A successful 200 response returned to Privy

For quick testing, you can also use services like webhook.site or RequestBin to get a temporary endpoint URL without setting up your own server.

Webhook delivery

Privy sends webhooks to your configured endpoint via Svix. The webhook system operates on an at least once delivery basis with automatic retries if the endpoint does not successfully respond.

Redundant webhook deliveries can be identified using the idempotency_key field where available, ensuring your application can safely handle duplicate events.

Retry behavior

Your endpoint must return a 2xx response for the webhook delivery to be considered successful. Anything else is considered an error response, and will be retried based on the following schedule, where each period is started following the failure of the preceding attempt:

Immediately
5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours (in addition to the previous)

After the final attempt, the message will be marked as a failure, and must be manually retried from the dashboard. If all attempts to your endpoint fail for 5 consecutive days, your endpoint will be automatically disabled.

Static IPs

Webhooks will be delivered from the following list of IP addresses:

228.126.217
112.21.217
24.126.164
148.139.208
1f24:64:8000::/56

Webhook signing key

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

Using `@privy-io/node`

Use the PrivyClient’s webhooks().verify method to verify an incoming webhook. Pass in the request body and svix headers. As an example, for a Next.js API request:

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID,
  appSecret: process.env.PRIVY_APP_SECRET,
  webhookSigningSecret: process.env.PRIVY_WEBHOOK_SIGNING_SECRET
});

// req is an input of type `NextApiRequest`
const verifiedPayload = await privy.webhooks().verify({
  payload: req.body,
  svix: {
    id: req.headers['svix-id'],
    timestamp: req.headers['svix-timestamp'],
    signature: req.headers['svix-signature']
  }
});

If the webhook payload is valid, the method returns the verified payload. If the webhook payload is invalid, the method throws an InvalidWebhookError.

Manual verification

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

User events

Transaction events

Wallet events

MFA events

Intent events

User operation events

API reference

Wallets

Account funding

Policies

Condition sets

Aggregations

Transactions

Key quorums

Intents

Users

Registering an endpoint

Testing the webhook setup

Step 1: Expose your local endpoint

Step 2: Create your webhook endpoint

Step 3: Register your endpoint in the dashboard

Step 4: Test your endpoint

Step 5: Verify receipt

Webhook delivery

Retry behavior

Static IPs

Webhook signing key

Using `@privy-io/node`

Manual verification

Webhook events reference

API reference

Wallets

Account funding

Policies

Condition sets

Aggregations

Transactions

Key quorums

Intents

Users

​Registering an endpoint

​Testing the webhook setup

​Step 1: Expose your local endpoint

​Step 2: Create your webhook endpoint

​Step 3: Register your endpoint in the dashboard

​Step 4: Test your endpoint

​Step 5: Verify receipt

​Webhook delivery

​Retry behavior

​Static IPs

​Webhook signing key

​Using @privy-io/node

​Manual verification

​Webhook events reference

User events

Transaction events

Wallet events

MFA events

Intent events

User operation events

Registering an endpoint

Testing the webhook setup

Step 1: Expose your local endpoint

Step 2: Create your webhook endpoint

Step 3: Register your endpoint in the dashboard

Step 4: Test your endpoint

Step 5: Verify receipt

Webhook delivery

Retry behavior

Static IPs

Webhook signing key

Using `@privy-io/node`

Manual verification

Webhook events reference