Webhooks look simple at first.
Your application exposes an HTTP endpoint, another service sends a JSON payload, and your code processes the event.
But a webhook receiver that works in a local demo is very different from one that can safely handle production traffic.
Here are five things every production webhook receiver should handle.
1. Verify every webhook request
A public webhook endpoint can receive requests from anyone on the internet.
Your application should verify that each request really came from the expected service before processing its contents.
A common approach is HMAC signature verification:
- The sender signs the raw request body with a shared secret.
- The signature is included in an HTTP header.
- Your receiver calculates the expected signature.
- The two signatures are compared using a timing-safe comparison.
Always verify the signature before parsing or processing the event.
It is also important to verify the raw request body. Parsing and serializing JSON again can change the bytes and cause a valid signature check to fail.
2. Make event processing idempotent
Webhook providers may deliver the same event more than once.
This can happen when your server times out, returns an error, or successfully processes an event but fails to return a response quickly enough.
Every event should have a unique identifier. Store that identifier before performing an action that must happen only once.
Without idempotency, one customer message could create multiple support tickets, notifications, or automated replies.
For a small application, event identifiers can be stored in a database table. Larger systems may use Redis or another shared idempotency store.
3. Respond quickly and process asynchronously
A webhook endpoint should not perform long-running work inside the HTTP request.
Instead, the receiver should:
- Verify the request.
- Validate the event.
- Store it or add it to a queue.
- Return a successful response.
- Process the event asynchronously.
This prevents temporary problems in a CRM, AI service, database, or notification system from blocking webhook delivery.
It also makes retry behavior easier to control.
4. Store the original event
Do not treat a Slack notification, CRM record, or application log as the only copy of an inbound event.
Store the original webhook event before transforming it.
This gives your team a reliable record for:
- Debugging delivery problems
- Reprocessing failed events
- Investigating customer reports
- Auditing automated actions
- Comparing old and new event schemas
Sensitive message contents should only be stored when necessary and should follow your privacy and retention policies.
5. Monitor delivery and processing failures
A production webhook system needs more than application logs.
Useful metrics include:
- Number of received events
- Invalid signature attempts
- Duplicate deliveries
- Processing duration
- Queue depth
- Downstream failures
- Events waiting for retry
Logs should include identifiers such as the event ID, delivery ID, provider, account ID, and response status.
Avoid writing API keys, signing secrets, access tokens, or unnecessary personal message contents to logs.
A simple production architecture
A reliable webhook pipeline can remain simple:
Webhook delivery
→ Signature verification
→ Event validation
→ Persistent storage
→ Processing queue
→ CRM, support system, AI agent, or notification service
The same structure can be used for payments, source control events, messaging platforms, and many other event-driven integrations.
The difficult part is rarely receiving the first request. The difficult part is making sure every valid event is processed safely, only once, and remains observable when another system fails.
Applying this to messaging platforms
These principles become especially important when receiving customer messages.
A support team may receive messages from Telegram, WhatsApp, LINE, Zalo, TikTok, and X. Each platform has different authentication methods and capabilities, but the receiving system still needs the same security, idempotency, storage, and monitoring boundaries.
At UnifyPort, we are building one API and a standard webhook event layer for these messaging platforms.
You can learn more about the event model and webhook design in the UnifyPort documentation:
Top comments (0)