Reference
Webhooks
Where Uncart tells your system what happened on its side: an order billed on an Uncart link, a refund taken off one, your shop's go-live changed, a test. One endpoint per mode, on a verified domain. Every delivery is signed with your shop's signing secret (`Uncart-Signature`), and every event has an `id` to drop repeats by. The webhooks guide shows how to check a signature.
Get your webhook endpoint
GET /v1/webhook-endpoint
A secret key with the webhooks:manage scope. See scopes.
The address Uncart sends this mode's events to, and whether your shop has a signing secret. 404 not_found when you have set none for this mode.
Answers
| Status | When |
|---|---|
200 | Your endpoint for the key's mode. |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | Nothing is at this address, or the shop has no such object. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/webhook-endpoint' \
-H "Authorization: Bearer $UNCART_KEY"
{
"url": "https://shop.example.com/uncart/webhooks",
"mode": "test",
"signing_secret": true,
"created_at": "2026-10-26T08:00:00.000Z",
"updated_at": "2026-10-26T08:00:00.000Z"
}
Set your webhook endpoint
PUT /v1/webhook-endpoint
A secret key with the webhooks:manage scope. See scopes.
Sets where Uncart sends this mode's events: a test key sets the test endpoint, a live key the live one. A new address replaces the last. It must be https:// on one of your verified domains, exactly, with a path and nothing else. Uncart checks it again before every delivery: an address no longer on a verified domain gets nothing.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
url | string | Required | Where Uncart sends this mode's events: https:// on one of your verified domains, exactly, with a path and nothing else (no user name, no port but 443, no query, no #fragment). Every delivery is signed, so the address needs no secret in it. |
Answers
| Status | When |
|---|---|
200 | The endpoint as Uncart now holds it. |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More |
413 | The body is over 1 MB. More |
415 | A body was sent that is not application/json. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/webhook-endpoint' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://shop.example.com/uncart/webhooks"
}'
{
"url": "https://shop.example.com/uncart/webhooks",
"mode": "test",
"signing_secret": true,
"created_at": "2026-10-26T08:00:00.000Z",
"updated_at": "2026-10-27T09:00:00.000Z"
}
curl 'https://api.uncart.ai/v1/webhook-endpoint' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://www.example.com/uncart/webhooks"
}'
Remove your webhook endpoint
DELETE /v1/webhook-endpoint
A secret key with the webhooks:manage scope. See scopes.
Removes this mode's endpoint. Events not yet delivered are given up, and nothing more is sent until you set one again.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Answers
| Status | When |
|---|---|
200 | Removed. |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | Nothing is at this address, or the shop has no such object. More |
409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/webhook-endpoint' \
-X DELETE \
-H "Authorization: Bearer $UNCART_KEY"
{
"deleted": true
}
Send a test event
POST /v1/webhook-endpoint/test
A secret key with the webhooks:manage scope. See scopes.
Queues one webhook.test event to this mode's endpoint, signed like every event: check your receiver end to end. Its id is in the answer. 404 not_found when you have set no endpoint for this mode.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Answers
| Status | When |
|---|---|
200 | The test event, queued. |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | Nothing is at this address, or the shop has no such object. More |
409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/webhook-endpoint/test' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY"
{
"id": "evt_ExampleEvent000000000001",
"type": "webhook.test"
}