API version

V2 · new integrations V1 · existing integrations

Webhooks & usage

Contract approved · validation in progress

Create an environment-scoped webhook endpoint. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`Idempotency-Key` header · Required	Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.

Idempotency-Key

header · Required

Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.

Request

`url` string · Required
`description` string · Optional
`events` array · Required

{
  "url": "https://integrator.example.com/webhooks/shipbuy",
  "description": "ERP shipment updates",
  "events": [
    "shipment.purchased",
    "tracking.updated"
  ]
}

Response

`201`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

List this integration webhook endpoints. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`cursor` query · Optional	Opaque continuation bound to tenant/environment/integration scope, filters, snapshot high-watermark and stable sort (updatedAt,id or documented resource-specific sort). Do not alter filters between pages. Incremental synchronization must include archive/deletion tombstones within the published retention window; snapshot expiry fails explicitly and requires a new scan.
`limit` query · Optional	integer
`updatedAfter` query · Optional	Exclusive UTC updated-time lower bound. For incremental sync keep a small overlap and deduplicate by id/version; cursor is authoritative within a scan.

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Retrieve webhook endpoint configuration. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`endpointId` path · Required	string

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Edit or disable webhook delivery. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`endpointId` path · Required	string
`Idempotency-Key` header · Required	Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.
`If-Match` header · Required	Exact strong ETag from the latest resource read. Required for PATCH; absent=428, stale=412. Quote/ship/split actions use explicit expectedVersion. An authorized idempotent replay returns its original committed result even if the resource is now newer.

Request

`url` string · Optional
`description` string · Optional
`events` array · Optional
`enabled` boolean · Optional

{
  "enabled": false
}

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`412`	If-Match does not match the current resource revision.
`422`	Field/business validation failed; details identify invalid fields.
`428`	Required concurrency precondition missing.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Delete a webhook endpoint. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

endpointId

path · Required

string

Idempotency-Key

header · Required

Response

`204`	Deleted/disabled; existing event audit remains readable under retention policy.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Only events visible under current resource scopes and integration restrictions, within published retention. Read events to reconcile missed deliveries; permissions are rechecked on every read. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`cursor` query · Optional	Opaque continuation bound to tenant/environment/integration scope, filters, snapshot high-watermark and stable sort (updatedAt,id or documented resource-specific sort). Do not alter filters between pages. Incremental synchronization must include archive/deletion tombstones within the published retention window; snapshot expiry fails explicitly and requires a new scan.
`limit` query · Optional	integer
`createdAfter` query · Optional	string
`type` query · Optional	string

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Retrieve one recoverable webhook event. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`eventId` path · Required	string

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`410`	The event has expired from the retention period.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Inspect webhook delivery attempts. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`endpointId` path · Required	string
`cursor` query · Optional	Opaque continuation bound to tenant/environment/integration scope, filters, snapshot high-watermark and stable sort (updatedAt,id or documented resource-specific sort). Do not alter filters between pages. Incremental synchronization must include archive/deletion tombstones within the published retention window; snapshot expiry fails explicitly and requires a new scan.
`limit` query · Optional	integer
`eventId` query · Optional	string

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

Uses the same event ID and a new delivery ID. Current endpoint destination, environment and resource scopes must still permit delivery. Does not repeat the business operation or create a billable tracker/verification. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "webhooks.manage"
      ]
    }
  ]
}

Parameters

`endpointId` path · Required	string
`eventId` path · Required	string
`Idempotency-Key` header · Required	Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover.

Request

`reason` string · Required

{
  "reason": "Receiver recovered after outage"
}

Response

`201`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`410`	The event has expired from the retention period.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

End is exclusive and must be after start; maximum range is 93 days. Only the authenticated test/live environment is returned; test usage cannot charge live funds.

Required permissions

{
  "anyOf": [
    {
      "allOf": [
        "usage.read"
      ]
    }
  ]
}

Parameters

`periodStart` query · Required	string
`periodEnd` query · Required	string

Response

`200`	Success.
`400`	Malformed JSON, unsupported query or invalid request syntax.
`401`	Missing, invalid, expired or revoked API key credential.
`403`	Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.
`404`	Resource absent or not visible in the authorized tenant/environment.
`409`	Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.
`422`	Field/business validation failed; details identify invalid fields.
`429`	Rate or paid-service limit exceeded. Respect Retry-After.
`500`	Unexpected server error; use requestId and query operation before retrying a side effect.
`503`	Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.

Download V2 contract (JSON)

On this page

Webhooks & usage

POST/v2/webhook-endpointsCreate an environment-scoped webhook endpointNot available

Create an environment-scoped webhook endpoint

Required permissions

Parameters

Request

Response

GET/v2/webhook-endpointsList this integration webhook endpointsNot available

List this integration webhook endpoints

Required permissions

Parameters

Response

GET/v2/webhook-endpoints/{endpointId}Retrieve webhook endpoint configurationNot available

Retrieve webhook endpoint configuration

Required permissions

Parameters

Response

PATCH/v2/webhook-endpoints/{endpointId}Edit or disable webhook deliveryNot available

Edit or disable webhook delivery

Required permissions

Parameters

Request

Response

DELETE/v2/webhook-endpoints/{endpointId}Delete a webhook endpointNot available

Delete a webhook endpoint

Required permissions

Parameters

Response

GET/v2/eventsList recoverable events for this integrationNot available

List recoverable events for this integration

Required permissions

Parameters

Response

GET/v2/events/{eventId}Retrieve one recoverable webhook eventNot available

Retrieve one recoverable webhook event

Required permissions

Parameters

Response

GET/v2/webhook-endpoints/{endpointId}/deliveriesInspect webhook delivery attemptsNot available

Inspect webhook delivery attempts

Required permissions

Parameters

Response

POST/v2/webhook-endpoints/{endpointId}/events/{eventId}/redeliverQueue redelivery of the same eventNot available

Queue redelivery of the same event

Required permissions

Parameters

Request

Response

GET/v2/usageRead API usage for a bounded periodNot available

Read API usage for a bounded period

Required permissions

Parameters

Response