Create webhook

cURL

curl -X POST "https://api.alura.io/v1/webhooks" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"url":"https://example.com/alura/webhooks","event_types":["order.*"]}'

const res = await fetch('https://api.alura.io/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
  },
  body: JSON.stringify({
    "url": "https://example.com/alura/webhooks",
    "event_types": [
      "order.*"
    ]
  }),
});
console.log(await res.json());

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/webhooks",
    method="POST",
    data=json.dumps({
      "url": "https://example.com/alura/webhooks",
      "event_types": [
        "order.*"
      ]
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

{
  "object": "webhook_endpoint",
  "id": "we_01JMOCK0000000000000000000",
  "url": "https://example.com/alura/webhooks",
  "description": null,
  "event_types": [
    "order.*"
  ],
  "shop_ids": null,
  "status": "enabled",
  "disabled_reason": null,
  "created_at": "2026-10-22T09:00:00.000Z",
  "secret": "whsec_ExampleExampleExampleExampleExampleExam0="
}

{
  "type": "https://docs.alura.io/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Invalid request",
  "suggestion": "Fix the request as the detail says, then send it again.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Unauthorized",
  "suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/credits_exhausted",
  "title": "API credits exhausted",
  "status": 402,
  "code": "credits_exhausted",
  "detail": "API credits exhausted",
  "suggestion": "Upgrade the plan or wait for the monthly reset.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/plan_required",
  "title": "Plan required",
  "status": 403,
  "code": "plan_required",
  "detail": "Plan required",
  "suggestion": "Upgrade the workspace plan to use this operation.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Not found",
  "suggestion": "Check the ID, or search for it first.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/method_not_allowed",
  "title": "Method not allowed",
  "status": 405,
  "code": "method_not_allowed",
  "detail": "Method not allowed",
  "suggestion": "Use one of the methods in the Allow header.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "Conflict",
  "suggestion": "Reload the resource and retry with its current state.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/rate_limited",
  "title": "Rate limited",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limited",
  "suggestion": "Wait for Retry-After, then retry.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "suggestion": "Retry; if it keeps failing, report the request_id.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/credits_unavailable",
  "title": "API credits unavailable",
  "status": 503,
  "code": "credits_unavailable",
  "detail": "API credits unavailable",
  "suggestion": "Retry shortly.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

cURL

curl -X POST "https://api.alura.io/v1/webhooks" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"url":"https://example.com/alura/webhooks","event_types":["order.*"]}'

const res = await fetch('https://api.alura.io/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
  },
  body: JSON.stringify({
    "url": "https://example.com/alura/webhooks",
    "event_types": [
      "order.*"
    ]
  }),
});
console.log(await res.json());

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/webhooks",
    method="POST",
    data=json.dumps({
      "url": "https://example.com/alura/webhooks",
      "event_types": [
        "order.*"
      ]
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

{
  "object": "webhook_endpoint",
  "id": "we_01JMOCK0000000000000000000",
  "url": "https://example.com/alura/webhooks",
  "description": null,
  "event_types": [
    "order.*"
  ],
  "shop_ids": null,
  "status": "enabled",
  "disabled_reason": null,
  "created_at": "2026-10-22T09:00:00.000Z",
  "secret": "whsec_ExampleExampleExampleExampleExampleExam0="
}

{
  "type": "https://docs.alura.io/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "Invalid request",
  "suggestion": "Fix the request as the detail says, then send it again.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Unauthorized",
  "suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/credits_exhausted",
  "title": "API credits exhausted",
  "status": 402,
  "code": "credits_exhausted",
  "detail": "API credits exhausted",
  "suggestion": "Upgrade the plan or wait for the monthly reset.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/plan_required",
  "title": "Plan required",
  "status": 403,
  "code": "plan_required",
  "detail": "Plan required",
  "suggestion": "Upgrade the workspace plan to use this operation.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Not found",
  "suggestion": "Check the ID, or search for it first.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/method_not_allowed",
  "title": "Method not allowed",
  "status": 405,
  "code": "method_not_allowed",
  "detail": "Method not allowed",
  "suggestion": "Use one of the methods in the Allow header.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "Conflict",
  "suggestion": "Reload the resource and retry with its current state.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/rate_limited",
  "title": "Rate limited",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limited",
  "suggestion": "Wait for Retry-After, then retry.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "suggestion": "Retry; if it keeps failing, report the request_id.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "https://docs.alura.io/errors/credits_unavailable",
  "title": "API credits unavailable",
  "status": 503,
  "code": "credits_unavailable",
  "detail": "API credits unavailable",
  "suggestion": "Retry shortly.",
  "retryable": true,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

Cost: Free.

curl -X POST "https://api.alura.io/v1/webhooks" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b2f4c1e-7a3d-4e8b-b6c5-1d0e2f3a4b5c" \
  -d '{"url": "https://example.com/alura/webhooks", "event_types": ["order.*"], "description": "Order notifications"}'

Needs the webhooks:write scope. Events start reaching the endpoint about 30 seconds after you create it.

The answer carries the endpoint’s signing secret (whsec_...) once. Store it: you need it to verify deliveries, and no other call shows it again.

Choose events and shops

`event_types` entry	Receives
`*`	Every event type
`order.paid`	That exact type
`order.*`	Every type that starts with `order.`

Give up to 20 entries. Alura doesn’t keep a list of Etsy’s types, so a type Etsy adds later reaches every entry that matches it. Order events reveal that an order exists, so *, order.* and any order. type need the orders:read scope as well. Without it, the call answers 403 insufficient_scope. shop_ids limits the endpoint to up to 100 of your connected shops. Leave it out, or set it to null, for every connected shop, including shops connected later. A shop that isn’t connected to the workspace answers 404.

The URL

It must be HTTPS on a public host: not localhost or a private, loopback, link-local or metadata address. No credentials or fragment in it, and at most 2,048 characters once percent-encoded.

Events before your first endpoint

Alura stores a workspace’s events only from its first endpoint on. Nothing from before exists, in deliveries or in List events.

Limits and retries

A workspace has at most 10 endpoints. Creating an 11th answers 409 conflict.Send an Idempotency-Key to retry safely: a retry with the same key and request answers the first result, with the same secret. See Idempotency.

Next, send a test event and check it arrives. How deliveries and retries work is on Webhooks and events.

Authorizations

Authorization

string

header

required

An API key: Authorization: Bearer alura_sk_....

Headers

Idempotency-Key

string

Makes a retry safe: the same key with the same request within 24 hours returns the first result (with Idempotent-Replayed: true) instead of writing again. The same key with a different request is a 409 conflict; while the first request still runs, 409 idempotency_processing.

Required string length: 1 - 255

Body

application/json

url

string

required

The HTTPS URL Alura sends events to: a public host.

Maximum string length: 2048

event_types

string[]

required

Event types to receive: * for every type, an exact type such as order.paid, or a prefix such as order.*. Order events need the orders:read scope too.

Required array length: 1 - 20 elements

Maximum string length: 200

Pattern: ^(\*|[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*(\.\*)?)$

shop_ids

string[] | null

Only events of these connected shops (Etsy shop IDs). Leave out or null for every connected shop, including shops connected later. A shop that isn't connected to the workspace is 404.

Required array length: 1 - 100 elements

Pattern: ^[1-9]\d{0,18}$

description

string | null

A note for yourself, up to 500 characters.

Maximum string length: 500

Response

object

string

required

Allowed value: "webhook_endpoint"

string

required

we_...

url

string

required

Where events are sent: an HTTPS URL.

description

string | null

required

Your note for this endpoint; null when none was set.

event_types

string[]

required

Etsy's event types this endpoint receives: * for every type, an exact type such as order.paid, or a prefix such as order.*.

shop_ids

string[] | null

required

Only events of these connected shops; null for every connected shop of the workspace, including shops connected later.

status

enum<string>

required

enabled receives events; disabled receives none until enabled again.

Available options:

enabled,

disabled

disabled_reason

enum<string> | null

required

Why a disabled endpoint is disabled: manual (PATCH) or failing (deliveries kept failing). Null while enabled.

Available options:

manual,

failing

created_at

string

required

When the endpoint was created (ISO 8601, UTC).

secret

string

required

The signing secret (whsec_...). Shown once, in this answer; store it to verify deliveries.

Overview

Research

Your shop

Etsy

Webhooks & events

Account

Choose events and shops

The URL

Authorizations

Headers

Body

Response

​Choose events and shops

​The URL

Authorizations

Headers

Body

Response

Choose events and shops

The URL