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

StatusWhen
200Your endpoint for the key's mode.
401No 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
403The key is valid, but its shop does not connect through the Uncart API. More
404Nothing is at this address, or the shop has no such object. More
422The 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
429Too 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
500Something 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
503Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More

Example

ShellRequest
curl 'https://api.uncart.ai/v1/webhook-endpoint' \
  -H "Authorization: Bearer $UNCART_KEY"
JSONAnswer 200
{
  "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

FieldTypeRequiredWhat it is
Idempotency-Keystring, in the headerOptionalA 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

FieldTypeRequiredWhat it is
urlstringRequiredWhere 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

StatusWhen
200The endpoint as Uncart now holds it.
400The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More
401No 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
403The key is valid, but its shop does not connect through the Uncart API. More
409A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More
413The body is over 1 MB. More
415A body was sent that is not application/json. More
422The 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
429Too 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
500Something 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
503Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More

Example

ShellRequest
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"
}'
JSONAnswer 200
{
  "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"
}
ShellRequest: not_verified
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

FieldTypeRequiredWhat it is
Idempotency-Keystring, in the headerOptionalA 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

StatusWhen
200Removed.
400The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More
401No 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
403The key is valid, but its shop does not connect through the Uncart API. More
404Nothing is at this address, or the shop has no such object. More
409A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More
422The 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
429Too 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
500Something 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
503Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More

Example

ShellRequest
curl 'https://api.uncart.ai/v1/webhook-endpoint' \
  -X DELETE \
  -H "Authorization: Bearer $UNCART_KEY"
JSONAnswer 200
{
  "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

FieldTypeRequiredWhat it is
Idempotency-Keystring, in the headerOptionalA 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

StatusWhen
200The test event, queued.
400The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More
401No 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
403The key is valid, but its shop does not connect through the Uncart API. More
404Nothing is at this address, or the shop has no such object. More
409A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More
422The 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
429Too 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
500Something 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
503Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More

Example

ShellRequest
curl 'https://api.uncart.ai/v1/webhook-endpoint/test' \
  -X POST \
  -H "Authorization: Bearer $UNCART_KEY"
JSONAnswer 200
{
  "id": "evt_ExampleEvent000000000001",
  "type": "webhook.test"
}