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 is currently a scale feature. To use webhooks, please upgrade your account in the Privy Dashboard.

​
Registering an endpoint

  1. 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 @privy-io/server-auth webhook documentation.

  2. In the dashboard, go to the Configuration > Webhooks page

  3. Add your new endpoint as the destination URL and select any event types you’d like to be notified for

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

Event NameTypeAction
User createduser.createdA user was created in the application.
User authenticateduser.authenticatedA user successfully logged into the application.
User linked accountuser.linked_accountA user successfully linked a new login method.
User unlinked accountuser.unlinked_accountA user successfully unlinked an existing login method.
User updated accountuser.updated_accountA user successfully updates the email or phone number linked to their account.
User transferred accountuser.transferred_accountA user successfully transferred their account to a new account.
Wallet created for useruser.wallet_createdA wallet (embedded or smart wallet) was successfully created for a user.
MFA enabledmfa.enabledA user has enabled MFA for their account.
MFA disabledmfa.disabledA user has disabled MFA for their account.
Private key exportedprivate_key.exportedA user has exported their private key from an embedded wallet.
Wallet recovery setupwallet.recovery_setupA user has set up wallet recovery for their embedded wallet.
Wallet recoveredwallet.recoveredA user has successfully recovered their embedded wallet.

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

​
Testing the webhook endpoint

Clicking the button once webhooks are configured for your application will trigger a test webhook (privy.test) to be sent to your endpoint of type with a string payload. You can use this to verify that your webhook endpoint is successfully receiving payloads from Privy.

​
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:

44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/52