API 版本

Webhook 與用量

契約已確認 · 驗證中

詳細欄位參考以英文顯示；欄位名稱和 API 值保持不變。

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.

所需權限

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

參數

`Idempotency-Key` header · 必填	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 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.

請求

`url` string · 必填
`description` string · 選填
`events` array · 必填

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

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`cursor` query · 選填	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 · 選填	integer
`updatedAfter` query · 選填	Exclusive UTC updated-time lower bound. For incremental sync keep a small overlap and deduplicate by id/version; cursor is authoritative within a scan.

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`endpointId` path · 必填	string

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`endpointId` path · 必填	string
`Idempotency-Key` header · 必填	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 · 必填	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.

請求

`url` string · 選填
`description` string · 選填
`events` array · 選填
`enabled` boolean · 選填

{
  "enabled": false
}

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

endpointId

path · 必填

string

Idempotency-Key

header · 必填

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`cursor` query · 選填	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 · 選填	integer
`createdAfter` query · 選填	string
`type` query · 選填	string

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`eventId` path · 必填	string

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`endpointId` path · 必填	string
`cursor` query · 選填	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 · 選填	integer
`eventId` query · 選填	string

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`endpointId` path · 必填	string
`eventId` path · 必填	string
`Idempotency-Key` header · 必填	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.

請求

`reason` string · 必填

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

回傳結果

`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.

下載 V2 契約（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.

所需權限

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

參數

`periodStart` query · 必填	string
`periodEnd` query · 必填	string

回傳結果

`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.

下載 V2 契約（JSON）

本篇目錄

Webhook 與用量

POST/v2/webhook-endpointsCreate an environment-scoped webhook endpoint尚未開放

Create an environment-scoped webhook endpoint

所需權限

參數

請求

回傳結果

GET/v2/webhook-endpointsList this integration webhook endpoints尚未開放

List this integration webhook endpoints

所需權限

參數

回傳結果

GET/v2/webhook-endpoints/{endpointId}Retrieve webhook endpoint configuration尚未開放

Retrieve webhook endpoint configuration

所需權限

參數

回傳結果

PATCH/v2/webhook-endpoints/{endpointId}Edit or disable webhook delivery尚未開放

Edit or disable webhook delivery

所需權限

參數

請求

回傳結果

DELETE/v2/webhook-endpoints/{endpointId}Delete a webhook endpoint尚未開放

Delete a webhook endpoint

所需權限

參數

回傳結果

GET/v2/eventsList recoverable events for this integration尚未開放

List recoverable events for this integration

所需權限

參數

回傳結果

GET/v2/events/{eventId}Retrieve one recoverable webhook event尚未開放

Retrieve one recoverable webhook event

所需權限

參數

回傳結果

GET/v2/webhook-endpoints/{endpointId}/deliveriesInspect webhook delivery attempts尚未開放

Inspect webhook delivery attempts

所需權限

參數

回傳結果

POST/v2/webhook-endpoints/{endpointId}/events/{eventId}/redeliverQueue redelivery of the same event尚未開放

Queue redelivery of the same event

所需權限

參數

請求

回傳結果

GET/v2/usageRead API usage for a bounded period尚未開放

Read API usage for a bounded period

所需權限

參數

回傳結果