```php php theme={null}
'received']);
```
```javascript javascript theme={null}
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());
const API_KEY = 'your_dora_api_key_here';
function verifySignature(payload, signature) {
const computed = crypto
.createHmac('sha256', API_KEY)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(computed)
);
}
app.post('/webhooks/dora', (req, res) => {
const signature = req.headers['x-dora-signature'];
if (!verifySignature(req.body, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = req.body;
// Process the event
console.log(`Received event: ${event.event}`);
console.log(`Delivery ID: ${event.data.delivery_id}`);
switch (event.event) {
case 'delivery.completed':
// Update your database
updateOrderStatus(event.data.order_number, 'delivered');
// Access receiver details
event.data.receiver_detail.forEach(receiver => {
console.log(`Delivered to: ${receiver.customer_name}`);
console.log(`Address: ${receiver.customer_address}`);
});
break;
case 'delivery.picked_up':
// Send SMS notification
const receiver = event.data.receiver_detail[0];
if (receiver) {
const phone = receiver.customer_phone_code + receiver.customer_phone_number;
sendSMS(phone, 'Your package is on the way!');
}
break;
}
res.json({ status: 'received' });
});
app.listen(3000);
```
```python python theme={null}
import hmac
import hashlib
import json
from flask import Flask, request, jsonify
app = Flask(__name__)
API_KEY = 'your_dora_api_key_here'
def verify_signature(payload, signature):
computed = hmac.new(
API_KEY.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, computed)
@app.route('/webhooks/dora', methods=['POST'])
def dora_webhook():
payload = request.get_data(as_text=True)
signature = request.headers.get('X-Dora-Signature', '')
if not verify_signature(payload, signature):
return jsonify({'error': 'Invalid signature'}), 401
event = request.json
# Process the event
if event['event'] == 'delivery.completed':
update_order_status(event['data']['order_number'], 'delivered')
# Access receiver details
for receiver in event['data']['receiver_detail']:
customer_name = receiver['customer_name']
customer_address = receiver['customer_address']
print(f"Delivered to {customer_name} at {customer_address}")
elif event['event'] == 'delivery.picked_up':
receiver = event['data']['receiver_detail'][0] if event['data']['receiver_detail'] else None
if receiver:
phone = receiver['customer_phone_code'] + receiver['customer_phone_number']
notify_customer(phone)
return jsonify({'status': 'received'})
if __name__ == '__main__':
app.run(port=5000)
```
## Retry Logic
If your endpoint returns a non-2xx status code or times out, Dora will retry the webhook:
* **Attempt 1**: Immediate
* **Attempt 2**: After 1 minute
* **Attempt 3**: After 5 minutes
* **Attempt 4**: After 15 minutes
After 3 failed attempts, the webhook will be marked as failed.
## Best Practices
1. **Respond Quickly**
* Return a 200 status code immediately
* Process the event asynchronously (queue it)
* Don't perform long-running operations in the webhook handler
2. **Verify Signatures**
* Always verify the `X-Dora-Signature` header
* Use constant-time comparison to prevent timing attacks
3. **Handle Duplicates**
* Webhooks may be sent multiple times
* Use `delivery_id` to detect and ignore duplicates
4. **Monitor Failures**
* Log all webhook requests
* Set up alerts for repeated failures
* Check the webhook events log in Dora dashboard
5. **Use HTTPS**
* Always use HTTPS for your webhook endpoint
* Dora will not send webhooks to HTTP URLs
## Testing Webhooks
You can test your webhook endpoint using tools like:
* **ngrok**: Expose your local server to the internet
* **RequestBin**: Inspect webhook payloads
* **Postman**: Manually send test requests
Example test payload:
```bash theme={null}
curl -X POST https://yoursite.com/webhooks/dora \
-H "Content-Type: application/json" \
-H "X-Dora-Signature: your_computed_signature" \
-H "X-Dora-Event: delivery.completed" \
-d '{
"event": "delivery.completed",
"timestamp": "2025-11-25T16:30:00Z",
"data": {
"delivery_id": "test-uuid",
"order_number": "TEST-001",
"status": "delivered"
}
}'
```
## Troubleshooting
**Webhooks not being received?**
* Check that your URL is publicly accessible
* Verify your server is running and responding
* Check firewall rules
* Review server logs for errors
**Signature verification failing?**
* Ensure you're using the correct API key
* Verify you're hashing the raw request body
* Check for encoding issues
**Need help?**
* Email: [support@dora.com](mailto:support@dora.com)
* Webhook logs: Available in your Dora dashboard