A successful webhook integration depends not on raw JSON delivery but on understanding the payload. Knowing the standard fields removes surprises.
A correct integration is not receiving the payload; it is understanding it. eventId and occurredAt are the spine of an idempotent design.
Standard fields
- eventId: unique id for idempotency.
- eventType: e.g. feedback.created, feedback.lowRating.
- occurredAt: ISO 8601 UTC timestamp.
- restaurantId: scope of the event.
- data: event-specific payload block.
Idempotency in practice
Never reprocess the same eventId. Keep a recent eventId set in a table or cache. At very high volume, a TTL-based cache is enough.
Response rules
Your endpoint must return 200 OK in under 5 seconds. For heavy work, accept first and process via a background queue. Otherwise the system retries and duplicate processing risk grows.
Kontrol listesi / Checklist
- eventId table exists.
- occurredAt processed as UTC.
- Endpoint replies 200 within 5 seconds.
- Unknown eventType handled gracefully.
- Response codes are monitored.
SSS / FAQ
What if I process a missing field?
Fields can be added over time. Ignoring unknown fields is the safest forward-compatibility pattern.
Is order guaranteed?
No. It is usually sequential, but network conditions affect order. Track processing time using occurredAt.