Find an event ID

Use the eventId at the top level of a webhook payload to correlate the event with callbacks, logs, and retries.

Before you begin

• Configure an HTTPS endpoint to receive Otter webhooks.
• Validate the webhook signature before processing the body.
• Keep the original payload available in your logs or event-processing record.

Steps

1. Inspect the JSON body sent to your webhook endpoint.

   Webhook payload

   LanguageJSON

   {
     "eventId": "cf0ce51b-d74e-40d3-b177-1925ab4edc0c",
     "eventTime": "2026-07-23T14:32:18Z",
     "eventType": "ping.ping",
     "metadata": {
       "storeId": "partner-store-123",
       "applicationId": "ad4ff59d-04c0-4c7d-8ca3-e3a673f8443d",
       "payload": {
         "message": "Hello World"
       }
     }
   }

2. Read eventId from the root of the payload. In the example, the event ID is cf0ce51b-d74e-40d3-b177-1925ab4edc0c.

   Do not use these other identifiers in its place:

   Field	What it identifies
   eventType	The kind of event, such as Ping webhook (ping.ping)
   metadata.resourceId	The resource affected by the event
   metadata.storeId	The store in your system

3. Store the event ID with your processing result. Use it as an idempotency key so a retry does not run the same work twice.

4. When an endpoint asks which event you are responding to, send the same value in the X-Event-Id request header. For example, the menu error callback (POST /v1/callback/error) requires this header.

Verify

Confirm that:

• your webhook log contains the top-level eventId;
• retries with the same event ID do not duplicate work;
• any callback X-Event-Id header exactly matches the webhook value.

Common failures

Symptom	Likely cause	Fix
Callback rejects the event ID	A resource or store ID was sent instead	Copy the top-level eventId unchanged
You cannot find an event ID	Only metadata.payload was logged	Log the complete webhook envelope after validating its signature
A retry creates duplicate work	The handler does not deduplicate events	Persist eventId and check it before processing

Next

• Understand events and webhooks
• Keep webhooks secure
• Review the payload for the webhook you consume in the API reference