Skip to main content

Events and webhooks

How Otter notifies your app when something happens outside a REST call you started — and how you should respond.

REST is how you initiate work. Webhooks are how Otter notifies you of work that started elsewhere (restaurant accept, menu publish request, store pause, report ready, and so on).

REST vs webhooks​

REST (your app → Otter)Webhooks (Otter → your app)
Who startsYouOtter or the restaurant
Typical useCreate an order, upsert a menu, pause a storeStatus changed, publish requested, credentials needed
AuthBearer access tokenValidate X-HMAC-SHA256 (see Authentication)
ResponseHTTP status for your request2xx quickly; process asynchronously

Most Integrations hubs use both.

Event lifecycle​

Event lifecycle from state change through signed webhook, 2xx acknowledge, and optional error callback

  1. Something changes in Otter (or a merchant action triggers it).
  2. Otter POSTs a signed JSON payload to your registered HTTPS URL.
  3. You validate the signature, return 2xx, and queue work.
  4. When a domain documents it, you may call an error callback so the merchant sees a clear failure (menus and delivery use this pattern).

Every outbound webhook includes the same UUID in the JSON body’s eventId field and the X-Event-Id request header. Persist this value before acknowledging the webhook. Send it back in callback endpoints that require X-Event-Id.

Acknowledge quickly​

  • Return 2xx as soon as the request is accepted for processing.
  • Do heavy work (DB writes, partner APIs) after the response.
  • Treat handlers as idempotent. The same event can arrive more than once through replay or workflow recovery even after a successful acknowledgement.

Delivery attempts and timeouts​

For each webhook delivery execution, Otter:

  • Applies a 30-second connection, read, write, and total call timeout.
  • Makes up to three attempts only for DNS or socket failures.
  • Waits approximately 100 ms before the second attempt and 500 ms before the third.
  • Does not retry an HTTP error response in that sender execution.

Do not use these attempts as a business-workflow timer. Otter can replay work outside this sender execution, so deduplicate with eventId and retain the result of every processing attempt.

Payload shapes live in the API reference and each Integrations hub’s Events section.

Error callbacks​

Some domains require an explicit failure report when your side cannot complete the work Otter asked for:

DomainPatternStart here
MenusPOST /v1/callback/error with event id + user-friendly reasonReport a failed menu event
DeliveryPOST /v1/delivery/callback/errorHandle delivery errors

Use a merchant-readable reason. Silent failures leave restaurants stuck with no message in Otter.

Security and registration​

  • Register HTTPS endpoints with your Account Representative (or via supported APIs where available).
  • Each endpoint has a secret — validate X-HMAC-SHA256 on every request. Deep how-to and code samples: Keep webhooks secure.

Next​

Implement signature validation (Keep webhooks secure), then subscribe to the event types listed on your Integrations hub Overview.