Webhook Best Practices for Self-Hosted Applications
Webhooks connect your self-hosted apps together. Here's how to implement, secure, and debug them properly.
What Are Webhooks?
Webhooks are HTTP callbacks. When an event occurs in one application, it sends an HTTP POST request to another application. Push notifications for servers.
Common Webhook Patterns
Git Push → Deploy
Your Git server sends a webhook to your deployment platform when you push code. The platform builds and deploys automatically.
Payment → Provision
Stripe/Polar sends a webhook when a payment succeeds. Your app provisions the user's subscription.
Form Submission → CRM
A form on your website sends a webhook to your CRM, creating a new contact.
Security Best Practices
Verify Signatures
Every webhook should include a signature header. The sender signs the payload with a shared secret. The receiver verifies the signature before processing.
Use HTTPS
Webhook payloads contain sensitive data. Always use HTTPS endpoints.
Validate the Payload
Don't trust webhook data blindly. Validate types, check required fields, and verify that referenced resources exist.
Idempotency
Webhooks can be delivered multiple times (retries). Design your handler to be idempotent — processing the same webhook twice should have the same result as processing it once.
Retry Logic
Webhook delivery fails sometimes. Good retry patterns:
Debugging Webhooks
Log Everything
Log the full request — headers, body, and your processing result. When something goes wrong, you need the raw data.
Use a Request Catcher
Tools like webhook.site let you inspect webhook payloads during development.
Monitor Failures
Track webhook success/failure rates. Alert on sustained failures.
TinyPod's Webhook System
TinyPod uses webhooks for:
All webhook endpoints verify signatures and implement retry logic.