curl -X POST "https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c"const res = await fetch('https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
"Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "webhook_delivery",
"id": "dlv_01JMOCK0000000000000000000",
"event_id": "evt_01JMOCK0000000000000000000",
"attempt": 1,
"status": "pending",
"http_status": null,
"duration_ms": null,
"error": null,
"created_at": "2026-10-22T09:15:03.000Z",
"next_attempt_at": "2026-10-22T09:15:03.000Z"
}{
"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"
}Send test event
Send a test event to a webhook endpoint to check that it receives and verifies deliveries.
curl -X POST "https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test" \
-H "Authorization: Bearer $ALURA_API_KEY" \
-H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c"const res = await fetch('https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
},
});
console.log(await res.json());import json
import os
import urllib.request
request = urllib.request.Request(
"https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test",
method="POST",
headers={
"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
"Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
},
)
with urllib.request.urlopen(request) as response:
print(json.load(response)){
"object": "webhook_delivery",
"id": "dlv_01JMOCK0000000000000000000",
"event_id": "evt_01JMOCK0000000000000000000",
"attempt": 1,
"status": "pending",
"http_status": null,
"duration_ms": null,
"error": null,
"created_at": "2026-10-22T09:15:03.000Z",
"next_attempt_at": "2026-10-22T09:15:03.000Z"
}{
"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 -X POST "https://api.alura.io/v1/webhooks/we_01JMOCK0000000000000000000/test" \
-H "Authorization: Bearer $ALURA_API_KEY"
webhooks:write scope, and orders:read as well on an endpoint with order event types.
Alura queues a webhook.test event, signed like every delivery, and answers with its delivery as pending. It’s sent within seconds, once, without retries. Follow it with List deliveries.
- The event has the usual envelope, with
shop_idset tonullanddataset to{"event_type": "webhook.test"}. - It works on a disabled endpoint too.
- It isn’t stored as an event, so List events doesn’t show it.
Authorizations
An API key: Authorization: Bearer alura_sk_....
Headers
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.
1 - 255Path Parameters
The webhook endpoint ID (we_...).
1 - 64"we_01JMOCK0000000000000000000"
Response
OK
"webhook_delivery"dlv_...: this attempt, also sent as the alura-delivery-id header.
The event sent (evt_...). It is also the webhook-id header, the same on every attempt of the event: de-duplicate on it.
1 for the first attempt, up to 8: retries come 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours after a failure.
pending: not sent yet (due at next_attempt_at). succeeded: your endpoint answered 2xx. failed: it did not, or the attempt was cancelled (error says why).
pending, succeeded, failed The HTTP status your endpoint answered; null when there was no answer or it wasn't sent.
How long the attempt took, connection included; null when it was not made.
Why an attempt failed without a usable answer: dns_failed, address_refused (the URL resolves to a private or local address), connect_failed, tls_failed, timeout (15 seconds), invalid_response, redirect_not_followed (a 3xx; redirects are never followed), invalid_url, internal_error (Alura could not finish the attempt; it is retried on the schedule); or why it was cancelled without being sent: endpoint_disabled, endpoint_changed (the endpoint's filters no longer want the event), event_expired. Null otherwise.
When the attempt was made; for a pending one, when it was queued.
For pending, when it is due; for failed, when the retry is due. Null when nothing follows.