文档目录

webhooks

Webhooks

Subscribe to events and Apus POSTs a signed JSON payload to your endpoint as things happen — no polling. Every request carries an X-Apus-Signature header: the HMAC-SHA256 of the raw request body keyed with your endpoint's signing_secret (returned once when you create the webhook). Recompute it and compare in constant time to verify the delivery is genuine and untampered. Subscribable events include product.updated, inventory.changed, sales_order.created, production_order.completed and invoice.paid. Deliveries are retried with exponential backoff, and you can inspect or replay them from the deliveries endpoints.

GET/v1/webhooksScope: webhooks:read

List webhooks

Returns a cursor-paginated list of the webhook endpoints registered for your account.

Query parameters

limitoptional	integerPage size, 1–200 (default 50).
cursoroptional	stringPagination cursor from a previous response.
activeoptional	booleanFilter by active status.

Request

curl "https://api.apusplatform.com/v1/webhooks" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "whk_5f3a",
      "url": "https://example.com/hooks/apus",
      "events": [
        "sales_order.created",
        "invoice.paid"
      ],
      "active": true,
      "created_at": "2026-07-14T09:02:11Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/v1/webhooksScope: webhooks:write

Create a webhook

Registers a webhook endpoint. The response includes the signing_secret — store it now; it is shown only once.

Body

urlrequired	stringHTTPS endpoint Apus POSTs signed payloads to.
eventsrequired	arrayEvent types to subscribe to, e.g. ["invoice.paid"].
activeoptional	booleanWhether to start delivering immediately (default true).

Request

curl -X POST "https://api.apusplatform.com/v1/webhooks" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/apus",
    "events": [
      "sales_order.created",
      "invoice.paid"
    ]
  }'

Response

{
  "id": "whk_5f3a",
  "url": "https://example.com/hooks/apus",
  "events": [
    "sales_order.created",
    "invoice.paid"
  ],
  "active": true,
  "signing_secret": "whsec_7Hk2pQ8sR4vN1mB6xL0dYt9",
  "created_at": "2026-07-20T02:10:00Z"
}

GET/v1/webhooks/{id}Scope: webhooks:read

Retrieve a webhook

Returns a single webhook endpoint by its id. The signing_secret is never returned again after creation.

Path parameters

idrequired

stringWebhook id.

Request

curl "https://api.apusplatform.com/v1/webhooks/whk_5f3a" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "id": "whk_5f3a",
  "url": "https://example.com/hooks/apus",
  "events": [
    "sales_order.created",
    "invoice.paid"
  ],
  "active": true,
  "created_at": "2026-07-14T09:02:11Z"
}

PATCH/v1/webhooks/{id}Scope: webhooks:write

Update a webhook

Updates mutable fields of a webhook. Only supplied fields change. Set active:false to pause delivery without deleting.

Path parameters

idrequired

stringWebhook id.

Body

urloptional	stringHTTPS endpoint Apus POSTs signed payloads to.
eventsoptional	arrayReplacement list of subscribed event types.
activeoptional	booleanPause (false) or resume (true) delivery.

Request

curl -X PATCH "https://api.apusplatform.com/v1/webhooks/whk_5f3a" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "sales_order.created",
      "invoice.paid",
      "inventory.changed"
    ]
  }'

Response

{
  "id": "whk_5f3a",
  "url": "https://example.com/hooks/apus",
  "events": [
    "sales_order.created",
    "invoice.paid",
    "inventory.changed"
  ],
  "active": true,
  "updated_at": "2026-07-20T02:12:00Z"
}

DELETE/v1/webhooks/{id}Scope: webhooks:write

Delete a webhook

Deletes a webhook endpoint. Delivery stops immediately and the signing_secret is revoked.

Path parameters

idrequired

stringWebhook id.

Request

curl -X DELETE "https://api.apusplatform.com/v1/webhooks/{id}" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

HTTP/1.1 204 No Content

GET/v1/webhooks/webhook-eventsScope: webhooks:read

List event types

Returns the catalog of event types you can subscribe a webhook to, grouped by module.

No parameters.

Request

curl "https://api.apusplatform.com/v1/webhooks/webhook-events" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "type": "product.updated",
      "module": "products",
      "desc": "A product's master data changed."
    },
    {
      "type": "inventory.changed",
      "module": "inventory",
      "desc": "On-hand quantity moved at a location."
    },
    {
      "type": "sales_order.created",
      "module": "sales",
      "desc": "A sales order was placed."
    },
    {
      "type": "production_order.completed",
      "module": "manufacturing",
      "desc": "A production order finished."
    },
    {
      "type": "invoice.paid",
      "module": "finance",
      "desc": "An invoice was fully settled."
    }
  ]
}

POST/v1/webhooks/{id}/testScope: webhooks:write

Send a test event

Sends a sample event to the endpoint so you can verify signature checking and connectivity. Returns the delivery it created.

Path parameters

idrequired

stringWebhook id.

Body

eventoptional

stringEvent type to simulate (default invoice.paid).

Request

curl -X POST "https://api.apusplatform.com/v1/webhooks/whd_2c9e/test" \
  -H "Authorization: Bearer $APUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "invoice.paid"
  }'

Response

{
  "id": "whd_2c9e",
  "webhook_id": "whk_5f3a",
  "event": "invoice.paid",
  "status": "delivered",
  "response_code": 200,
  "created_at": "2026-07-20T02:14:00Z"
}

GET/v1/webhooks/{id}/deliveriesScope: webhooks:read

List deliveries

Returns a cursor-paginated log of delivery attempts for a webhook. Use status to find failures worth retrying.

Path parameters

idrequired

stringWebhook id.

Query parameters

limitoptional	integerPage size, 1–200 (default 50).
cursoroptional	stringPagination cursor from a previous response.
statusoptional	stringFilter by delivery status: delivered, failed, pending.

Request

curl "https://api.apusplatform.com/v1/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "data": [
    {
      "id": "whd_2c9e",
      "event": "invoice.paid",
      "status": "failed",
      "response_code": 500,
      "attempts": 3,
      "created_at": "2026-07-19T18:40:02Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/webhooks/webhook-deliveries/{id}Scope: webhooks:read

Retrieve a delivery

Returns a single delivery attempt, including the signed payload sent and the endpoint's response.

Path parameters

idrequired

stringDelivery id.

Request

curl "https://api.apusplatform.com/v1/webhooks/webhook-deliveries/whd_2c9e" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "id": "whd_2c9e",
  "webhook_id": "whk_5f3a",
  "event": "invoice.paid",
  "status": "failed",
  "response_code": 500,
  "attempts": 3,
  "signature": "sha256=9f2a1c...",
  "payload": {
    "id": "inv_8a12",
    "event": "invoice.paid",
    "amount": {
      "amount": 4500000,
      "currency": "VND"
    }
  },
  "created_at": "2026-07-19T18:40:02Z"
}

POST/v1/webhooks/webhook-deliveries/{id}/retryScope: webhooks:write

Retry a delivery

Re-sends a failed or pending delivery immediately with the same signed payload. Returns the new attempt.

Path parameters

idrequired

stringDelivery id.

Request

curl -X POST "https://api.apusplatform.com/v1/webhooks/webhook-deliveries/whd_2c9e/retry" \
  -H "Authorization: Bearer $APUS_TOKEN"

Response

{
  "id": "whd_2c9e",
  "webhook_id": "whk_5f3a",
  "event": "invoice.paid",
  "status": "delivered",
  "response_code": 200,
  "attempts": 4,
  "created_at": "2026-07-20T02:16:00Z"
}

准备好集成了吗？

在账户控制台中创建 API 客户端以获取凭证，或与集成工程师沟通您的使用场景。

获取 API 凭证联系集成工程师

← PrevEDM – Documents