Skip to main content

App Webhooks

Installed marketplace apps can define merchant-scoped webhook endpoints for app-specific event delivery.

Implemented route family​

Current routes include:

  • GET /api/v1/merchant/apps/installations/{installationId}/webhook_endpoints
  • POST /api/v1/merchant/apps/installations/{installationId}/webhook_endpoints
  • POST /api/v1/merchant/apps/webhook_endpoints/{endpointId}
  • POST /api/v1/merchant/apps/webhook_endpoints/{endpointId}/rotate_secret

Legacy-compatible merchant paths may also be available under api/merchant/apps/*.

List webhook endpoints for an installation​

GET /api/v1/merchant/apps/installations/{installationId}/webhook_endpoints

Create a webhook endpoint​

POST /api/v1/merchant/apps/installations/{installationId}/webhook_endpoints

Typical request fields include:

  • url

The create response includes the generated signing secret and the created endpoint metadata.

Update a webhook endpoint​

POST /api/v1/merchant/apps/webhook_endpoints/{endpointId}

Typical request fields include:

  • url
  • enabled

Endpoint metadata​

Endpoint metadata includes:

  • endpoint identifier
  • installation identifier
  • URL
  • enabled flag
  • consecutive failures
  • disabled timestamp
  • last delivery timestamp
  • last delivery status

Operational note​

App webhook endpoints are distinct from the general webhook_endpoints public route family. They are installation-scoped app framework endpoints owned by a merchant.