API reference Webhooks and events Add a webhook endpoint

Add a webhook endpoint

POST methodhttps://api.anyshop.io/v1/webhook_endpoints

The answer carries its signing secret once. Endpoints must be public https addresses.

Scope webhooks:write
Idempotent with Idempotency-Key
Works while the store is suspended

Body

application/json2 required, 2 optional

urlstring requiredA public https address. anyshop never follows redirects or calls private networksUp to 2,048 characters
descriptionstring For you, up to 200 charactersUp to 200 characters
events"all" or array of enums required"all" (now and later), or a list of event typesallorder.paidorder.fulfilledorder.refundeddispute.createdstock.lowlicense.activated
signingenum How deliveries are signed: hmac (a shared secret, the default) or ed25519hmaced25519

Headers

Idempotency-Keystring Up to 255 characters. A retry with the same key and request gets the first answer, without running twice (24 hours).

Example

as_live_ or as_test_

curl -X POST https://api.anyshop.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $ANYSHOP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.pixelforge-supply.com/anyshop",
    "events": [
      "order.paid"
    ]
  }'

{
  "object": "webhook_endpoint",
  "id": "whe_01m3rs9d2f4k6m8p0r2t4v6x8z",
  "url": "https://api.pixelforge-supply.com/anyshop",
  "description": "",
  "livemode": false,
  "events": [
    "order.paid"
  ],
  "signing": "hmac",
  "status": "enabled",
  "disabled_reason": null,
  "failing_since": "2026-10-02T14:21:07.000Z",
  "created_at": "2026-10-02T14:21:07.000Z",
  "secret": {
    "object": "webhook_secret",
    "algorithm": "hmac",
    "value": "whsec_Q3s9mV1dGx7PqL2nW8rT5kZ0bY4cH6jF9aE1uS3oKP4="
  }
}

The IDs and keys in these examples are made up. Every schema is in the OpenAPI document, served at https://api.anyshop.io/v1/openapi.json.

Returns

The webhook_endpoint object.

Errors

Status and error.type

400invalid_requestThe request is not valid; error.param names the field
401authenticationNo API key, or it is not valid
403permissionThe key does not have the scope this needs, it is a test key where only a live key may act (the catalog), or the store is suspended (store_suspended)
404not_foundNot found in the key's store and mode
409conflictConflicts with the object's state (type conflict), or an Idempotency-Key reused for another request (type idempotency, code idempotency_key_reused)
429rate_limitedToo many requests; see Retry-After