Managing a Shopify store means tracking every order, customer action, and inventory change in real time. The Shopify webhooks API sends instant notifications to your application when specific events occur, eliminating constant polling and keeping systems synchronized.
This guide covers setup, configuration, and troubleshooting to help you implement webhooks effectively.
Summary
- Webhook fundamentals: Real-time event notifications through HTTP POST requests
- Authentication setup: API credentials and HMAC validation for security
- Creation methods: Admin API, GraphQL, or Shopify admin dashboard
- Topic selection: Orders, inventory, customers, and product events
- Endpoint configuration: HTTPS requirements and response handling
- Troubleshooting: Delivery failures and payload processing solutions
What Is the Shopify Webhooks API?
The Shopify webhooks API pushes real-time updates from your store to external applications when specific events occur. Instead of polling for changes, webhooks send HTTP POST requests to your endpoint instantly.
How Webhooks Work
When you register a Shopify webhook, Shopify monitors events and notifies your application:
- Event occurs (new order, product update, customer creation)
- Shopify detects the event
- Shopify sends HTTP POST with event data to your URL
- Your application processes the payload
- Your application responds with 200 OK
This event-driven architecture synchronizes systems without consuming API rate limits through constant polling.
Key Benefits
Webhooks deliver updates within seconds, eliminate polling overhead, and scale automatically with store growth. Your API rate limit stays available for actual data operations instead of checking for changes.
Understanding Webhook Topics and Events
Shopify offers over 100 webhook topics covering store operations. Choosing relevant topics ensures your application receives the necessary notifications without processing unnecessary data.
Common Webhook Topics
| Category | Webhook Topic | Use Case |
| Orders | orders/create | Trigger fulfillment when orders arrive |
| Orders | orders/updated | Track order status changes |
| Products | products/create | Sync new products to catalogs |
| Products | products/update | Update product information |
| Inventory | inventory_levels/update | Monitor stock levels |
| Customers | customers/create | Add customers to CRM |
| Customers | customers/updated | Sync customer data |
| Fulfillment | fulfillments/create | Update shipping tracking |
Selecting the Right Topics
Consider your application’s core functionality when choosing topics. Inventory systems need inventory_levels/update and products/update, while CRM integrations require customer-focused topics. Start with essential topics and add more as your integration matures.
Setting Up Authentication for Shopify Webhooks API
Authentication credentials verify your application’s identity and authorize webhook creation. Shopify uses API access tokens for this process.
Creating a Custom App
Navigate to Shopify admin:
- Go to Settings > Apps and sales channels > Develop apps
- Click “Create an app” and provide a name
- Configure Admin API scopes
- Install the app to generate access tokens
Store the Admin API access token securely—you’ll need it for all Shopify webhook operations.
Required API Scopes
Your custom app needs specific permissions:
- read_webhooks: View existing subscriptions
- write_webhooks: Create, update, and delete webhooks
Additional scopes depend on topics. Order webhooks need read_orders. Product webhooks require read_products.
Securing Credentials
Store API tokens in environment variables. Use secret management services in production. Rotate tokens regularly and revoke unused ones immediately.
Creating Webhooks Through the Admin API
The Admin REST API provides straightforward webhook creation using HTTP requests. This method works well for managing multiple stores programmatically.
Prerequisites
Before making API calls, gather:
- Your store’s myshopify.com URL
- Admin API access token
- Webhook topic for subscription
- Publicly accessible HTTPS endpoint URL
Your endpoint must support HTTPS—Shopify rejects HTTP URLs for security.
API Request Example
Create a Shopify webhook using REST API:
bash
curl -X POST \
https://your-store.myshopify.com/admin/api/2024-01/webhooks.json \
-H “X-Shopify-Access-Token: YOUR_ACCESS_TOKEN” \
-H “Content-Type: application/json” \
-d ‘{
“webhook”: {
“topic”: “orders/create”,
“address”: “https://your-app.com/webhooks/orders”,
“format”: “json”
}
}’
Replace placeholders with your actual store name, access token, and endpoint URL.
Understanding the Response
Successful creation returns:
json
{
“webhook”: {
“id”: 901431826,
“address”: “https://your-app.com/webhooks/orders”,
“topic”: “orders/create”,
“created_at”: “2024-01-12T10:30:00-05:00”,
“format”: “json”,
“api_version”: “2024-01”
}
}
Save the webhook ID for updates or deletions.
Common Errors
| Error Code | Cause | Solution |
| 401 Unauthorized | Invalid access token | Verify token and app installation |
| 422 Unprocessable Entity | Invalid topic or URL | Confirm topic name and endpoint |
| 429 Too Many Requests | Rate limit exceeded | Implement exponential backoff |
Creating Webhooks Using GraphQL API
GraphQL offers flexibility for complex webhook operations. The Shopify webhook API supports GraphQL for developers preferring strongly-typed queries.
GraphQL Mutation
Use webhookSubscriptionCreate:
graphql
mutation {
webhookSubscriptionCreate(
topic: ORDERS_CREATE
webhookSubscription: {
format: JSON,
callbackUrl: “https://your-app.com/webhooks/orders”
}
) {
webhookSubscription {
id
topic
format
}
userErrors {
field
message
}
}
}
Handling Responses
Check the userErrors array first. Empty means success. Non-empty indicates problems like invalid callback URLs or missing permissions.
Configuring Your Webhook Endpoint
Your webhook endpoint must handle incoming POST requests reliably. Proper configuration ensures you receive all notifications without failures.
Endpoint Requirements
Shopify expects:
- HTTPS only: HTTP rejected
- Public accessibility: Reachable from Shopify servers
- Fast response: 200 status within 5 seconds
- No redirects: Shopify doesn’t follow 301/302
Building a Basic Receiver
Node.js Express example:
javascript
const express = require(‘express’);
const app = express();
app.post(‘/webhooks/orders’, express.raw({type: ‘application/json’}), (req, res) => {
const hmac = req.get(‘X-Shopify-Hmac-SHA256’);
const topic = req.get(‘X-Shopify-Topic’);
// Verify webhook (covered next section)
// Process payload
const payload = JSON.parse(req.body);
// Respond immediately
res.status(200).send(‘Webhook received’);
// Handle async processing
processWebhook(payload, topic);
});
app.listen(3000);
Response Time Best Practices
Return 200 immediately upon receiving requests. Queue payload processing for asynchronous handling. Avoid external API calls before responding. Multiple consecutive failures cause Shopify to disable your subscription.
Verifying Webhook Authenticity with HMAC
Shopify includes an HMAC signature with each Shopify webhook, allowing you to verify authenticity.
HMAC Validation
HMAC uses your app’s client secret to generate unique signatures. Recalculate the signature and compare it to the provided header to confirm the webhook came from Shopify.
Implementation
Node.js verification:
javascript
const crypto = require(‘crypto’);
function verifyWebhook(body, hmacHeader) {
const hash = crypto
.createHmac(‘sha256’, process.env.SHOPIFY_CLIENT_SECRET)
.update(body, ‘utf8’)
.digest(‘base64’);
return hash === hmacHeader;
}
app.post(‘/webhooks/orders’, express.raw({type: ‘application/json’}), (req, res) => {
const hmac = req.get(‘X-Shopify-Hmac-SHA256’);
if (!verifyWebhook(req.body, hmac)) {
return res.status(401).send(‘Verification failed’);
}
res.status(200).send(‘Verified’);
});
Never process webhooks without verification.
Security Considerations
Store your client secret in environment variables. Rotate periodically. Use the raw request body before parsing or middleware modifications.
Testing Webhooks Before Production
Shopify Testing Tools
Use admin dashboard testing at Settings > Notifications > Webhooks. Select your subscription and click “Send test notification” to send sample payloads without triggering real store events.
Local Development
Expose development servers using Ngrok:
bash
ngrok http 3000
Ngrok provides an HTTPS URL for testing. Update to the production endpoint before going live.
Validating Delivery
Confirm success through server logs showing POST requests, 200 response status, “Success” in Shopify admin activity log, and correct payload processing. Failed deliveries appear in logs with error details.
Managing Webhook Subscriptions
Listing Active Webhooks
bash
curl -X GET \
https://your-store.myshopify.com/admin/api/2024-01/webhooks.json \
-H “X-Shopify-Access-Token: YOUR_ACCESS_TOKEN”
Updating and Deleting
Modify endpoint URLs with PUT requests or remove unused subscriptions with DELETE:
| Operation | Endpoint | Method |
| List webhooks | /admin/api/2024-01/webhooks.json | GET |
| Update webhook | /admin/api/2024-01/webhooks/{id}.json | PUT |
| Delete webhook | /admin/api/2024-01/webhooks/{id}.json | DELETE |
Troubleshooting Common Issues
Delivery Failures
- Slow responses: Return 200 immediately and process asynchronously.
- SSL issues: Verify SSL configuration and certificate validity.
- Unreachable endpoint: Check server status and firewall rules.
Missing Webhooks
Implement queueing systems for burst handling. Verify active subscriptions regularly through the API.
Payload Errors
Handle different character encodings explicitly. Implement flexible parsing that doesn’t break on schema changes.
Access delivery logs at Settings > Notifications > Webhooks for timestamps, response codes, and error messages.
Best Practices for Production
Implementing Retry Logic
javascript
async function processWithRetry(payload, topic, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
await processWebhook(payload, topic);
return true;
} catch (error) {
if (attempt === maxRetries) return false;
await new Promise(resolve =>
setTimeout(resolve, 1000 * Math.pow(2, attempt))
);
}
}
}
Scaling and Monitoring
Use message queues (RabbitMQ, AWS SQS) to buffer webhooks during spikes. Deploy multiple receivers behind load balancers for horizontal scaling. Track delivery success rates, monitor latency, and alert on failures.
Advanced Webhook Patterns
Webhooks enable sophisticated integration patterns beyond basic notifications.
Combining Multiple Topics
- Order fulfillment: Subscribe to orders/create, fulfillments/create, and fulfillments/update for complete lifecycle tracking.
- Inventory sync: Combine products/update, products/delete, and inventory_levels/update for accurate multi-channel stock levels.
Webhook-Triggered Workflows
When orders/create fires, automatically verify inventory, calculate shipping routes, generate picking lists, and send confirmation emails. This eliminates manual intervention and reduces processing time.
Event Aggregation
Batch multiple events for efficient processing. Collect inventory_levels/update webhooks over short periods and batch updates to reduce system load while maintaining near-real-time accuracy.
API Versioning and Migration
Shopify updates the webhooks API regularly. Each webhook subscription locks to a specific API version, determining payload structure and available topics. Shopify supports versions for 12 months after release.
Migrating Versions
Update subscriptions before deprecation: review the changelog for breaking changes, update payload processing code, test with the new version, delete old subscriptions, and create new ones with the updated version.
Check current versions by listing webhooks:
bash
curl -X GET \
https://your-store.myshopify.com/admin/api/2024-01/webhooks.json \
-H “X-Shopify-Access-Token: YOUR_ACCESS_TOKEN”
Integration Examples
ERP System Integration
Subscribe to orders/create and orders/updated to push orders into ERP automatically. Use Shopify Admin API to sync changes back, eliminating manual data entry.
Inventory Management
Process inventory_levels/update webhooks to update warehouse systems and sales channels simultaneously. Combine with inventory management apps for multi-location tracking.
Marketing Automation
Add new customers to email platforms when customers/create fires. Trigger abandoned cart sequences and product recommendations using orders/create.
Key Takeaways
- Configure the Shopify webhooks API using REST or GraphQL with proper authentication and HMAC verification
- Choose webhook topics strategically to avoid unnecessary notifications
- Build endpoints that respond within 5 seconds and process payloads asynchronously
- Implement retry logic, monitoring, and error handling for production reliability
- Stay current with API versions and migrate before deprecation deadlines
Conclusion
The Shopify webhooks API transforms integrations into real-time systems responding instantly to business events. Proper implementation with authentication, verification, and error handling eliminates polling overhead while enabling sophisticated automation.
Ready to streamline your Shopify integration? Our team builds robust webhook solutions that scale with your business. Contact us to discuss your integration needs.
Frequently Asked Questions
What Is the Difference Between Shopify Webhooks and the Shopify Webhook API?
Shopify webhooks are the event notification system that sends real-time updates when store events occur. The Shopify webhook API is the programmatic interface (REST or GraphQL) used to create, manage, and configure webhook subscriptions.
How Many Shopify Webhooks Can I Create on a Store?
Shopify limits each store to 15 webhook subscriptions per topic. You can create multiple subscriptions for different topics, but each topic allows 15 endpoints. This limit applies across all connected apps.
Do Shopify Webhooks Affect API Rate Limits?
No, receiving webhooks doesn’t count against your Shopify API rate limit. However, making API calls in response to webhooks does count. Monitor usage and implement throttling during high-traffic periods.
How Long Does Shopify Retry Failed Webhook Deliveries?
Shopify attempts delivery for up to 48 hours after initial failure. Attempts follow exponential backoff with increasing delays. After 19 consecutive failures, Shopify automatically disables the subscription.
Can I Create Custom Webhook Topics for My Store?
No, Shopify webhooks only support predefined topics for standard events like orders, products, customers, and inventory. You cannot create custom topics for app-specific logic. Implement your own notification system for custom events.
What Happens to Webhooks When I Uninstall an App?
Shopify automatically deletes all webhooks created by an app during uninstallation. This prevents orphaned webhooks from sending notifications to nonexistent endpoints. Reinstalling requires recreating webhook subscriptions.
How Do I Test Shopify Webhooks Without Affecting Live Data?
Use development stores from the Partner Dashboard to test safely. Development stores function normally but don’t process real transactions. Alternatively, use “Send test notification” in Shopify admin to send sample payloads without triggering actual events.
Can Shopify Webhooks Send Data to Multiple Endpoints?
Yes, create multiple subscriptions for the same topic pointing to different endpoints. Each subscription fires independently when events occur, sending payloads to all configured endpoints simultaneously.
