Intermediate
How to set up webhooks on Stripe
Quick Answer
Setting up webhooks on Stripe involves creating an endpoint in your Stripe Dashboard, configuring the events you want to listen for, and implementing the webhook handler in your application. You'll need to verify webhook signatures for security and test the integration thoroughly.
Prerequisites
- Active Stripe account
- Basic understanding of HTTP requests
- Access to your application's server or webhook endpoint
- Developer permissions on your Stripe account
1
Access the Webhooks section in Stripe Dashboard
Log into your Stripe Dashboard and navigate to Developers > Webhooks. Click the Add endpoint button to start creating your webhook configuration.
Tip
Make sure you're in the correct environment (test or live mode) before creating webhooks.
2
Configure your endpoint URL
Enter your webhook endpoint URL in the Endpoint URL field. This should be a publicly accessible HTTPS URL where Stripe will send webhook events (e.g.,
https://yourdomain.com/webhooks/stripe). Add an optional description to identify the webhook's purpose.Tip
Use HTTPS for security - Stripe requires secure endpoints for live mode webhooks.
3
Select events to listen for
In the Events to send section, choose Select events and pick the specific events you want to receive (e.g.,
Common events include:
payment_intent.succeeded, customer.created, invoice.payment_failed). Alternatively, select Listen to all events if you need comprehensive coverage.Common events include:
payment_intent.succeeded- successful paymentssubscription.updated- subscription changescustomer.subscription.deleted- subscription cancellations
Tip
Only listen for events you actually need to reduce unnecessary webhook calls and improve performance.
4
Save and retrieve your webhook secret
Click Add endpoint to save your webhook configuration. Once created, click on your new webhook endpoint and locate the Signing secret section. Click Reveal to show your webhook signing secret (starts with
whsec_). Copy and securely store this secret in your application's environment variables.Tip
The signing secret is crucial for verifying webhook authenticity - never expose it in your code or version control.
5
Implement webhook handling in your application
Create a webhook handler in your application that:
Example signature verification:
- Accepts POST requests at your configured endpoint
- Verifies the webhook signature using Stripe's libraries
- Processes the event data based on event type
Example signature verification:
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);Tip
Always verify webhook signatures to ensure requests are actually from Stripe and haven't been tampered with.
6
Test your webhook endpoint
In the Stripe Dashboard, go to your webhook endpoint and click Send test webhook. Select an event type and click Send test webhook to trigger a test event. Monitor your application logs to ensure the webhook is received and processed correctly. Check the webhook's Recent deliveries section for delivery status and response details.
Tip
Test with multiple event types to ensure your handler works correctly for all scenarios you're listening for.
7
Monitor and maintain your webhooks
Regularly check the Recent deliveries section in your webhook configuration to monitor delivery success rates. Set up proper logging and error handling in your application. Configure retry logic for failed webhook processing, and ensure your endpoint returns appropriate HTTP status codes (200 for success, 4xx/5xx for errors).
Tip
Stripe automatically retries failed webhook deliveries, but implementing idempotency in your handler prevents duplicate processing.
Troubleshooting
Webhooks are not being received
Verify your endpoint URL is publicly accessible and returns a 200 status code. Check your firewall settings and ensure your server is running. Test the URL directly with a tool like
curl or Postman.Webhook signature verification fails
Ensure you're using the correct signing secret from the webhook configuration. Verify you're passing the raw request body (not parsed JSON) to the signature verification function. Check that your endpoint secret matches the webhook in the dashboard.
Webhook deliveries show as failed
Check your application logs for errors in webhook processing. Ensure your endpoint returns a 200 HTTP status code for successful processing. Verify your handler doesn't timeout - Stripe expects responses within 30 seconds.
Duplicate webhook events are being processed
Implement idempotency by checking the
event.id against previously processed events. Store processed event IDs in your database to prevent duplicate handling. Use Stripe's idempotency_key for API calls triggered by webhooks.Ready to get started with Stripe?
Put this tutorial into practice. Visit Stripe and follow the steps above.
Visit Stripe →