This reference provides detailed documentation for all webhook event types available in Privy, including example payloads for each event.
Webhooks is currently a scale feature. To use webhooks, please upgrade your account in the Privy
Dashboard.
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.
To set up webhooks, go to the webhooks page in the Privy Dashboard.
Event structure All webhook events follow a consistent structure with the event type included as a type field:
{ "type" : "event.type" // Event-specific data } User and authentication events user.createdTriggered when a new user is created in your app.
{ "type" : "user.created" , "user" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [], "mfa_methods" : [], "has_accepted_terms" : true , "is_guest" : false } } user.authenticatedTriggered when a user successfully authenticates with your app.
Show Example payload (email authentication)
{ "type" : "user.authenticated" , "user" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [ { "type" : "email" , "address" : "[email protected] " , "verified_at" : 1716153600 , "first_verified_at" : 1716153600 , "latest_verified_at" : 1716153600 } ], "mfa_methods" : [ { "type" : "totp" , "verified_at" : 1716153600 } ], "has_accepted_terms" : true , "is_guest" : false }, "account" : { "type" : "email" , "address" : "[email protected] " , "verified_at" : 1716153600 , "first_verified_at" : 1716153600 , "latest_verified_at" : 1716153600 } } user.linked_accountTriggered when a user links a new account (email, wallet, social, etc.) to their Privy account.
Email account
Ethereum wallet
Google OAuth
{ "type" : "user.linked_account" , "user" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [], "mfa_methods" : [], "has_accepted_terms" : true , "is_guest" : false }, "account" : { "type" : "email" , "address" : "[email protected] " , "verified_at" : 1716153600 , "first_verified_at" : 1716153600 , "latest_verified_at" : 1716153600 } } user.unlinked_accountTriggered when a user unlinks an account from their Privy account.
{ "type" : "user.unlinked_account" , "user" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [], "mfa_methods" : [], "has_accepted_terms" : true , "is_guest" : false }, "account" : { "type" : "email" , "address" : "[email protected] " , "verified_at" : 1716153600 , "first_verified_at" : 1716153600 , "latest_verified_at" : 1716153600 } } user.updated_accountTriggered when a user updates an existing linked account.
{ "type" : "user.updated_account" , "user" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [], "mfa_methods" : [], "has_accepted_terms" : true , "is_guest" : false }, "account" : { "type" : "email" , "address" : "[email protected] " , "verified_at" : 1716153600 , "first_verified_at" : 1716153600 , "latest_verified_at" : 1716153600 } } user.transferred_accountTriggered when an account is transferred from one user to another (typically during user merging).
{ "type" : "user.transferred_account" , "fromUser" : { "id" : "did:privy:clu2wsin402h9h9kt6ae7dfuh" }, "toUser" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [], "mfa_methods" : [], "has_accepted_terms" : true , "is_guest" : false }, "account" : { "type" : "email" , "address" : "[email protected] " , "verified_at" : 1716153600 , "first_verified_at" : 1716153600 , "latest_verified_at" : 1716153600 }, "deletedUser" : true } user.wallet_createdTriggered when a user creates a new embedded wallet.
{ "type" : "user.wallet_created" , "user" : { "id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "created_at" : 1716153600 , "linked_accounts" : [], "mfa_methods" : [], "has_accepted_terms" : true , "is_guest" : false }, "wallet" : { "type" : "wallet" , "address" : "0x123" , "chain_type" : "ethereum" } } Transaction events transaction.broadcastedTriggered when a transaction has been submitted to the network but has not yet been included in a block.
{ "type" : "transaction.broadcasted" , "wallet_id" : "wallet-123" , "transaction_id" : "tx-123" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" } transaction.confirmedTriggered when a transaction has been included in at least one block that has been confirmed on the network.
{ "type" : "transaction.confirmed" , "wallet_id" : "wallet-123" , "transaction_id" : "tx-123" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" } transaction.execution_revertedTriggered when a transaction’s execution reverted (typically due to a smart contract error).
{ "type" : "transaction.execution_reverted" , "wallet_id" : "r3mbxxfmzsuxxw3guxxha2xx" , "transaction_id" : "537e327d-7382-4e61-93e5-0241c72d0793" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" } transaction.still_pendingTriggered when a transaction is still pending after the expected confirmation time. Listen to this webhook to trigger transaction speed-ups .
{ "type" : "transaction.still_pending" , "wallet_id" : "wallet-123" , "transaction_id" : "tx-123" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" , "transaction_request" : { "from" : "0x123" , "to" : "0x456" , "value" : "0x0" , "data" : "0x" , "gas" : "0x5208" , "gasPrice" : "0x4a817c800" } } Failures are uncommon overall, but more likely to occur on Base and Polygon than other chains
(<1% of transactions). To ensure transactions get confirmed, follow the guide on transaction
replacement to speed up stalled transactions. transaction.failedTriggered when a transaction has been pending for too long, signaling that it will not be included on-chain. This can happen when the gas fee is too low given the current activity on the blockchain.
{ "type" : "transaction.failed" , "wallet_id" : "wallet-123" , "transaction_id" : "tx-123" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" } transaction.replacedTriggered when a transaction was replaced (e.g., speed-up or cancel operation). This is only applicable to EVM chains.
{ "type" : "transaction.replaced" , "wallet_id" : "wallet-123" , "transaction_id" : "tx-123" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" } transaction.provider_errorTriggered when a custodial wallet transaction request has been rejected by the custodian or encountered an error. This can happen when attempting to spend funds that haven’t been fully screened by the custodian yet, or when a transaction does not meet the custodian’s compliance requirements.
{ "type" : "transaction.provider_error" , "wallet_id" : "wallet-123" , "transaction_id" : "tx-123" , "caip2" : "eip155:1" , "transaction_hash" : "0x123" } Wallet and funds events wallet.funds_depositedTriggered when funds are deposited into a wallet.
Deposit webhooks are available for select chains on Tier 3 and Tier 2. To see which exact chains
are supported, go to the Dashboard webhooks page . Native token
ERC-20 token
SPL token
{ "type" : "wallet.funds_deposited" , "wallet_id" : "wallet-123" , "idempotency_key" : "124" , "caip2" : "eip155:1" , "asset" : { "type" : "native-token" , "address" : null }, "amount" : "1000000000000000000" , "transaction_hash" : "0x456" , "sender" : "0x789" , "recipient" : "0xabc" , "block" : { "number" : 12346 } } An idempotent ID that uniquely identifies the deposit. In cases where the webhook triggers more
than once, the idempotency_key will match.
Absolute amount of the transaction. Denominated based on the asset (e.g. wei for EVM, or lamports
for SOL). Stringified to maintain precision from BigInt.
wallet.funds_withdrawnTriggered when funds are withdrawn from a wallet.
Native token
ERC-20 token
SPL token
{ "type" : "wallet.funds_withdrawn" , "wallet_id" : "wallet-123" , "idempotency_key" : "124" , "caip2" : "eip155:1" , "asset" : { "type" : "native-token" , "address" : null }, "amount" : "1000000000000000000" , "transaction_hash" : "0x456" , "sender" : "0x789" , "recipient" : "0xabc" , "block" : { "number" : 12346 } } Security events wallet.private_key_exportTriggered when a user exports their private key from an embedded wallet.
{ "type" : "wallet.private_key_export" , "user_id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "wallet_id" : "wallet-123" , "wallet_address" : "0x123" } wallet.recovery_setupTriggered when a user sets up wallet recovery.
{ "type" : "wallet.recovery_setup" , "user_id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "wallet_id" : "wallet-123" , "wallet_address" : "0x123" , "method" : "recovery_encryption_key" } wallet.recoveredTriggered when a user successfully recovers their wallet.
{ "type" : "wallet.recovered" , "user_id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "wallet_id" : "wallet-123" , "wallet_address" : "0x123" } MFA events mfa.enabledTriggered when multi-factor authentication is enabled for a user.
{ "type" : "mfa.enabled" , "user_id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "method" : "totp" } MFA methods: sms, totp (authenticator app), passkey
mfa.disabledTriggered when multi-factor authentication is disabled for a user.
{ "type" : "mfa.disabled" , "user_id" : "did:privy:cfbsvtqo2c22202mo08847jdux2z" , "method" : "sms" } 
