Skip to main content

Receive Etsy Webhook

POST 
/api/webhooks/etsy

Receives an order notification from Etsy. One endpoint serves every connected Etsy shop; the shop is identified by shop_id in the payload. No bearer token — requests are authenticated with a Standard Webhooks HMAC signature.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Headers:

  • webhook-id (required) — Unique message ID. Etsy retries with the same ID; duplicates are ignored.
  • webhook-timestamp (required) — Unix timestamp in seconds. Requests more than 5 minutes old or in the future are rejected.
  • webhook-signature (required) — Space-separated list of v1,<signature> entries, where the signature is base64(HMAC-SHA256(<webhook-id>.<webhook-timestamp>.<raw body>)) keyed with the base64-decoded signing secret (the part after whsec_).

Body:

  • event_type (string) — order.paid, order.canceled, order.shipped, or order.delivered. Other event types are acknowledged and ignored.
  • resource_url (string) — Etsy API URL of the affected receipt.
  • shop_id (integer) — Etsy shop ID.

Behavior: a valid notification is stored and the referenced order is re-imported from Etsy in the background. The receiver always answers 200 {"ok": true} for a valid signature (including unknown shops and ignored events) and 401 for an invalid or missing signature.

Request​

Responses​

OK

Response Headers
    Content-Type