Cresora Commerce Documentation

Manage webhook subscriptions — event types, delivery URLs, HMAC secret rotation. See `webhooks:` section for event schemas.

ℹServer-to-server API

Run the examples on this page from your backend against the sandbox host. The API sends no CORS headers, so browser JavaScript cannot read its responses, and an API key must never be exposed in a browser. There is no interactive console here. Generating a client instead? Download the OpenAPI spec (YAML).

List webhook subscriptions

GET/webhook-subscriptions

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

Obtain via Partner Portal → Settings → API keys. Keys are only shown in full at creation/rotation time — Cresora does not retain the full value in retrievable form. Rotate any key that may have been exposed via logs, client code, or source control.

In: header

Query Parameters

cursor?string

Opaque pagination cursor from previous response. Do not parse.

Lengthlength <= 256

page_size?integer

Items per page (1–100).

Range1 <= value <= 100

Default25

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/webhook-subscriptions"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "url": "http://example.com",      "description": "string",      "state": "ACTIVE",      "event_type_patterns": [        "string"      ],      "merchant_scope_mode": "PARTNER_DEFAULT",      "merchant_ids": [        "006a4151-5819-498d-ace5-e10247e992c5"      ],      "secret_preview": "string",      "last_delivered_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "next_cursor": "string",    "has_more": true,    "total_count": 0  }}

Create webhook subscription

POST/webhook-subscriptions

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Format: 1–128 characters of letters, digits, . _ : -. Anything else is rejected with 400 validation_error. The character set is narrower than base64: padded base64 (+ / =) is NOT accepted, base64url is. The key is forwarded verbatim to the payment gateway on transaction creates, so it must satisfy the gateway's key contract too — rejecting locally gives you an actionable error instead of an opaque upstream failure mid-request.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Retrying after an indeterminate failure. On 502 gateway_outcome_unknown the transaction is recorded as pending and the outcome is not yet known — retry with the SAME key (a fresh key risks a double charge) or poll the transaction. This is also what a gateway-side "an earlier request with this key is still in flight" response surfaces as.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url*string

HTTPS endpoint (port 443). MUST resolve to a public IP. SSRF defenses reject RFC 1918, link-local, loopback, IPv6 ULA, .internal, .svc, .cluster.local, .local.

Formaturi

description?string

Lengthlength <= 200

event_type_patterns*array<>

Items1 <= items <= 100

merchant_scope_mode?string

Merchant filter (default PARTNER_DEFAULT — a partner-level endpoint). MERCHANT_OVERRIDE requires a non-empty merchant_ids; PARTNER_DEFAULT must omit it. See the webhooks spec §9 "Merchant scope" for routing precedence.

Value in

"PARTNER_DEFAULT"
"MERCHANT_OVERRIDE"

merchant_ids?array<>

Required (non-empty) when merchant_scope_mode is MERCHANT_OVERRIDE; omit otherwise.

Itemsitems <= 500

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/webhook-subscriptions" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "url": "http://example.com",    "event_type_patterns": [      "string"    ]  }'

{  "subscription": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "url": "http://example.com",    "description": "string",    "state": "ACTIVE",    "event_type_patterns": [      "string"    ],    "merchant_scope_mode": "PARTNER_DEFAULT",    "merchant_ids": [      "006a4151-5819-498d-ace5-e10247e992c5"    ],    "secret_preview": "string",    "last_delivered_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z"  },  "secret": "string"}

Get webhook subscription

GET/webhook-subscriptions/{subscriptionId}

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "http://example.com",  "description": "string",  "state": "ACTIVE",  "event_type_patterns": [    "string"  ],  "merchant_scope_mode": "PARTNER_DEFAULT",  "merchant_ids": [    "006a4151-5819-498d-ace5-e10247e992c5"  ],  "secret_preview": "string",  "last_delivered_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Update webhook subscription

PATCH/webhook-subscriptions/{subscriptionId}

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url?string

Formaturi

description?|

Lengthlength <= 200

event_type_patterns?array<>

Items1 <= items <= 100

merchant_scope_mode?string

Present = change the merchant scope; absent = leave unchanged. MERCHANT_OVERRIDE requires a non-empty merchant_ids; PARTNER_DEFAULT (revert to a partner-level endpoint) must omit it. A merchant_ids without a mode is rejected (400).

Value in

"PARTNER_DEFAULT"
"MERCHANT_OVERRIDE"

merchant_ids?array<>

Itemsitems <= 500

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "url": "http://example.com",  "description": "string",  "state": "ACTIVE",  "event_type_patterns": [    "string"  ],  "merchant_scope_mode": "PARTNER_DEFAULT",  "merchant_ids": [    "006a4151-5819-498d-ace5-e10247e992c5"  ],  "secret_preview": "string",  "last_delivered_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}

Delete webhook subscription

DELETE/webhook-subscriptions/{subscriptionId}

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

Response Body

`application/problem+json`

curl -X DELETE "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

Rotate HMAC secret

POST/webhook-subscriptions/{subscriptionId}/rotate-secret

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate-secret" \  -H "Idempotency-Key: string"

{  "secret": "string",  "rotated_at": "2019-08-24T14:15:22Z"}

Send a synchronous test event to the subscription URL

POST/webhook-subscriptions/{subscriptionId}/test-delivery

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/test-delivery" \  -H "Idempotency-Key: string"

{  "envelope_id": "cd819e97-5425-4178-8fcc-567f1dc109ce",  "status_code": 0,  "latency_ms": 0,  "response_body_preview": "string",  "response_headers": {    "property1": "string",    "property2": "string"  },  "error": "string"}

List webhook delivery history

GET/webhook-subscriptions/{subscriptionId}/deliveries

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

Query Parameters

cursor?string

Pagination token from a previous page's pagination.next_cursor. Encodes (created_at, id) of the last row served. Treat as opaque.

page_size?integer

Bounded [1, 200]. Default 25.

Range1 <= value <= 200

Default25

status?string

Filter by per-attempt outcome.

Value in

"SUCCEEDED"
"FAILED_PERMANENT"
"FAILED_TRANSIENT"
"EXHAUSTED"
"REJECTED_SSRF"
"SKIPPED_SUSPENDED"

from?string

Inclusive lower bound on created_at (ISO 8601 UTC). Combine with to for date-range scans.

Formatdate-time

to?string

Exclusive upper bound on created_at (ISO 8601 UTC). from <= to required; reversed range returns 400.

Formatdate-time

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/deliveries"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",      "event_type": "string",      "attempt_number": 1,      "status": "SUCCEEDED",      "http_status": 0,      "duration_ms": 0,      "error_message": "string",      "next_retry_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "next_cursor": "string",    "has_more": true,    "total_count": 0  }}

Redeliver a historical webhook event

POST/webhook-subscriptions/{subscriptionId}/deliveries/{eventId}/redeliver

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

subscriptionId*string

Formatuuid

eventId*string

The original event_id from the webhook envelope. Look up the historical delivery row for this event and enqueue a fresh attempt with the same envelope (same event_id, idempotency_key, and data payload).

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header X-Idempotent-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/webhook-subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/deliveries/497f6eca-6276-4993-bfeb-53cbbbba6f08/redeliver" \  -H "Idempotency-Key: string"

{  "redelivery_id": "7d12b267-de78-4054-b178-2eccdc158225",  "subscription_id": "aa11a4c2-a467-43db-b413-c4ab0f5cf627",  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",  "enqueued_at": "2019-08-24T14:15:22Z"}

List subscribable webhook event types

GET/webhook-event-types

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/webhook-event-types"

[  {    "event_type": "string",    "description": "string",    "source_context": "string"  }]

Webhook metadata — retry policy + per-event-type limit

GET/webhook-metadata

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk_<prefix>_<random>

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/webhook-metadata"

{  "max_subscriptions_per_event_type": 0,  "max_merchant_ids_per_subscription": 0,  "retry_max_attempts": 0,  "retry_window": "string",  "retry_policy_description": "string"}

Webhooks

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

204

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

429application/problem+json

500application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

202application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`