Webhooks

Webhooks notify an integration about public resource changes without requiring constant polling. They use the same public representations returned by the corresponding read endpoints.

Registering an endpoint

1. Expose a public HTTPS URL that can read the raw request body.
2. Call POST /api/public/v1/webhook-endpoints with the URL and selected event types.
3. Store the returned whsec_... secret. It is shown only on creation and rotation.
4. Verify signatures before processing events.
5. Return a 2xx response only after durably accepting the event.

An endpoint belongs to the API key that creates it. The API key must have the corresponding read scope for every selected event type.

Events

Event	Data schema	Required scope
item.created	Item	items:read
item.updated	Item	items:read
item.deleted	Item and external identifiers	items:read
listing.status_changed	Listing	items:read
listing.failed	Listing	items:read
listing.delisting_failed	Listing	items:read
item_feed.finished	Item feed	items:read
sale.created	Sale	sales:read
sale.updated	Sale	sales:read
shipment.tracking_updated	Sale	sales:read
shipping_batch.finished	Shipping batch	shipping:read
shipping_batch.action_required	Shipping batch	shipping:read
shipping_batch.failed	Shipping batch	shipping:read
purchase.created	Purchase	purchases:read
purchase.updated	Purchase	purchases:read
offer.created	Offer	offers:read
offer.updated	Offer	offers:read

Item and sale events can result from changes made outside this API. Their external item IDs are personalized for the receiving API key. Item feeds and shipping batches are delivered only to the API key that created them.

Envelope

{
  "id": "01J...",
  "type": "sale.created",
  "api_version": "v1",
  "created_at": "2026-08-24T12:00:00Z",
  "data": {}
}

Use id as the deduplication key. Delivery is at least once.

Signature verification

Mascot sends these headers:

• Mascot-Event-Id
• Mascot-Event-Type
• Mascot-Delivery-Id
• Mascot-Delivery-Attempt
• Mascot-Webhook-Timestamp
• Mascot-Webhook-Signature

The signature is:

HMAC-SHA256(secret, timestamp + "." + raw_request_body)

The header contains v1=<hex digest>. Calculate the digest from the unmodified request bytes, compare it in constant time, and reject timestamps outside your accepted tolerance. Do not parse or transform the JSON before verifying the signature.

Delivery policy

• Any 2xx response acknowledges the event.
• Redirects are not followed.
• 410 Gone disables the endpoint immediately.
• Network errors and other non-2xx responses are retried.
• There are up to ten attempts over 72 hours.
• 429 and 503 may use Retry-After.
• Duplicate delivery is possible before or after a successful attempt.

When an endpoint has delivery failures its status becomes FAILING; a later success restores ACTIVE. Disable an endpoint while performing maintenance if it should receive no new events. Rotating the secret takes effect for subsequent deliveries, so deploy the new secret before discarding the old one when coordinating a rotation.