/admin/webhooksThe answer is the only time the signing secret is shown. Deliveries start with the next event; send a test event to check the endpoint. Admin webhooks get the moderation queues and editorial catalog changes, while the person who makes them is on staff.
collector.createAdminWebhook()admin:webhooks:writeIdempotency-KeyX-Request-Idurlstring (uri)requiredhttps:// on port 443 or 1024 and up, on a public host. No user name or password in it (check the signature instead).
1–2048 characters
eventsarray of enumrequiredThe event types to send: GET /webhooks/events lists them and who may have each.
1–50 items
collection.item.createdcollection.item.updatedcollection.item.deletedwishlist.matchhold.requestedhold.acceptedhold.declinedhold.expiredhold.cancelledhold.completedquestion.askedquestion.answeredlisting.soldlisting.out_of_stockmoderation.item.createdmoderation.item.resolvedcatalog.record.changedexport.readydescriptionstring or nullat most 200 characters
activebooleanStart sending at once (the default), or make it off.
default true
201CreatedThe webhook, and its secret (shown once).
A webhook just made, or its secret just rotated: the only time the secret is shown.
secretstringrequiredThe signing secret (whsec_…). Store it now: it can’t be shown again. Verify each delivery with it.
invalid_requestinvalid_jsoninvalid_idempotency_keyinvalid_webhook_url
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
invalid_webhook_url: The URL isn’t one webhooks may use: not https, a port under 1024 (other than 443), a user name or password in it, or a host that doesn’t resolve or resolves to a private address.
insufficient_scope: With an API key: subscribing to an event also needs the scope that reads it.
not_found: Not an admin (moderator): the same 404 as a missing route.
idempotency_in_progresstoo_many_webhooks
idempotency_in_progress: The first request with this key is still running.
too_many_webhooks: Already at the most webhooks allowed here (10; 20 for admin).
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
idempotency_key_reused: This key was used for a different request.
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).