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.

The following functionality exists for wallets reconstituted server-side. More on Privy architecture here

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:

User events

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 updated 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 enabled MFA for their account.
MFA disabled	mfa.disabled	A user disabled MFA for their account.

Wallet events

Event Name	Type	Action
Wallet archived	wallet.archived	A wallet was archived via the API.
Wallet restored	wallet.restored	A wallet was restored from archive.
Funds deposited	wallet.funds_deposited	Funds were deposited into a user’s embedded wallet.
Funds withdrawn	wallet.funds_withdrawn	Funds were withdrawn from a user’s embedded wallet.
Private key exported	wallet.private_key_export	A user exported their private key from an embedded wallet.
Seed phrase exported	wallet.seed_phrase_export	A user exported their seed phrase from an embedded wallet.
Wallet recovery setup	wallet.recovery_setup	A user set up wallet recovery for their embedded wallet.
Wallet recovered	wallet.recovered	A user successfully recovered their embedded wallet.

Transaction events

Event Name	Type	Action
Transaction broadcasted	transaction.broadcasted	A transaction was submitted to the network and is awaiting confirmation.
Transaction confirmed	transaction.confirmed	A transaction was confirmed on-chain.
Transaction failed	transaction.failed	A transaction failed to be submitted to the network.
Execution reverted	transaction.execution_reverted	A transaction was confirmed on-chain but execution reverted.
Transaction replaced	transaction.replaced	A transaction was replaced by another transaction (e.g. speed-up or cancel).
Transaction still pending	transaction.still_pending	A transaction remained pending for an extended period.
Provider error	transaction.provider_error	A provider error occurred while submitting a transaction.

Wallet action events

Event Name	Type	Action
Swap	wallet_action.swap.*	A token swap was created, succeeded, was rejected, or failed.
Transfer	wallet_action.transfer.*	A token transfer was created, succeeded, was rejected, or failed.
Earn deposit	wallet_action.earn_deposit.*	A vault deposit was created, succeeded, was rejected, or failed. See earn webhooks.
Earn withdrawal	wallet_action.earn_withdraw.*	A vault withdrawal was created, succeeded, was rejected, or failed. See earn webhooks.
Earn incentive claim	wallet_action.earn_incentive_claim.*	An incentive claim was created, succeeded, was rejected, or failed. See earn webhooks.

Intent events

Event Name	Type	Action
Intent created	intent.created	An intent was proposed and is awaiting approval.
Intent authorized	intent.authorized	A team member authorized an intent.
Intent rejected	intent.rejected	An intent was rejected by a team member.
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 events

Event Name	Type	Action
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

Verify a webhook with the SDK

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`.
// `headers` must include `svix-id`, `svix-timestamp`, and `svix-signature`.
const verifiedPayload = privy.webhooks().verify({
  payload: req.body,
  headers: req.headers
});

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.

Webhook events reference

User events

Events for user creation, authentication, and account linking. Includes user.created, user.authenticated, and more.

Wallet events

Events for deposits, withdrawals, and wallet security. Includes wallet.funds_deposited, wallet.funds_withdrawn, and more.

Transaction events

Events for transaction lifecycle. Includes transaction.confirmed, transaction.failed, and more.

Wallet action events

Events for swaps, transfers, and earn actions. Includes wallet_action.swap.*, wallet_action.transfer.*, and more.

MFA events

Events for multi-factor authentication. Includes mfa.enabled and mfa.disabled.

Intent events

Events for the intent approval lifecycle. Includes intent.created, intent.authorized, and intent.rejected.

User operation events

Events for ERC-4337 UserOperation lifecycle. Includes user_operation.completed.

API reference

Wallets

Wallet actions

Accounts

Policies

Condition sets

Aggregations

Transactions

Key quorums

Intents

Users

Labs

Registering an endpoint

User events

Wallet events

Transaction events

Wallet action events

Intent events

User operation events

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

Verify a webhook with the SDK

Manual verification

Webhook events reference

User events

Wallet events

Transaction events

Wallet action events

MFA events

Intent events

User operation events

​Registering an endpoint

​User events

​Wallet events

​Transaction events

​Wallet action events

​Intent events

​User operation events

​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

​Verify a webhook with the SDK

​Manual verification

​Webhook events reference

User events

Wallet events

Transaction events

Wallet action events

MFA events

Intent events

User operation events

Registering an endpoint

User events

Wallet events

Transaction events

Wallet action events

Intent events

User operation events

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

Verify a webhook with the SDK

Manual verification

Webhook events reference