WebhooksWebhook endpoints
Open app

Webhook endpoints

Webhook endpoints are HTTPS URLs that receive HTTP POSTs for the events your store cares about, signed per the Standard Webhooks spec. Subscribe each endpoint to one or more event types from the curated catalog and rotate its signing secret on demand.

Endpoints

The webhook endpoint object

The webhook endpoint object is the shape returned by endpoints in this collection. Its attributes are listed below.

Attributes

activeboolean

Whether the endpoint is currently receiving deliveries. Disabled endpoints stay in the list but are skipped by the dispatcher.

apiVersionstring

Pinned event payload version. Reserved for forward compatibility; today every endpoint receives the latest shape.

createdAttimestamp

Time the endpoint was created.

descriptionstring

Optional human-readable label shown in the dashboard.

idstring

Unique identifier for the webhook endpoint.

storeIdstring

Store this endpoint belongs to.

subscribedEventsarray of strings

Event types (or glob patterns) the endpoint subscribes to. Patterns are constrained to the published catalog — see GET /v1/webhooks/event-types.

updatedAttimestamp

Time the endpoint was last updated.

urlurl

Absolute URL that receives the signed event POSTs.

Example response
{  "active": false,  "apiVersion": "string",  "createdAt": "2026-01-01T00:00:00.000Z",  "description": "Production webhook",  "id": "whe_01HJZQK7XJ8R9YGEWABCDEFGHJK",  "storeId": "str_01HJZQK7XJ8R9YGEWABCDEFGHJK",  "subscribedEvents": [    "product.created",    "product.updated"  ],  "updatedAt": "2026-01-01T00:00:00.000Z",  "url": "https://example.com/webhooks/mercel"}

List all webhook endpoints

Lists every webhook endpoint configured for the current store. Returned in a single page today — the response envelope still uses Pagination so the surface is forward-compatible.

Path & query parameters

limitinteger

Maximum number of items to return per page. Defaults to 20, capped at 100.

1 ≤ value ≤ 100
pagestring

Opaque pagination token. Pass the value returned in nextPageUrl / previousPageUrl rather than constructing one — the encoding is internal and may change.

curl -X GET "https://api.mercel.app/v1/webhooks/endpoints"
Response200
{
  "data": [
    {
      "active": true,
      "apiVersion": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "description": "Production webhook",
      "id": "whe_01HJZQK7XJ8R9YGEWABCDEFGHJK",
      "storeId": "str_01HJZQK7XJ8R9YGEWABCDEFGHJK",
      "subscribedEvents": [
        "product.created",
        "product.updated"
      ],
      "updatedAt": "2019-08-24T14:15:22Z",
      "url": "https://example.com/webhooks/mercel"
    }
  ],
  "nextPageUrl": "http://example.com",
  "previousPageUrl": "http://example.com"
}

Retrieve a webhook endpoint

Retrieves the details of an existing webhook endpoint by id.

Path & query parameters

endpointIdstringRequired

The id of the webhook endpoint to operate on.

curl -X GET "https://api.mercel.app/v1/webhooks/endpoints/whe_01hh9zzzzzzzzzzzzzzzzzzzzz"
Response200
{
  "endpoint": {
    "active": true,
    "apiVersion": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "description": "Production webhook",
    "id": "whe_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "storeId": "str_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "subscribedEvents": [
      "product.created",
      "product.updated"
    ],
    "updatedAt": "2019-08-24T14:15:22Z",
    "url": "https://example.com/webhooks/mercel"
  }
}

Create a webhook endpoint

Creates a webhook endpoint and issues its initial signing secret. The raw secret is returned exactly once — save it now, as the platform retains a hash only.

Body parameters

apiVersionstring

Pinned event payload version. Reserved for forward compatibility.

descriptionstring

Optional human-readable label shown in the dashboard.

length ≤ 500
subscribedEventsarray of stringsRequired

Event types (or glob patterns) the endpoint subscribes to. Patterns are constrained to the published catalog — see GET /v1/webhooks/event-types.

urlurlRequired

Absolute https URL the webhook events should be POSTed to.

curl -X POST "https://api.mercel.app/v1/webhooks/endpoints" \  -H "Content-Type: application/json" \  -d '{    "subscribedEvents": [      "product.created",      "product.updated"    ],    "url": "https://example.com/webhooks/mercel"  }'
Response201
{
  "endpoint": {
    "active": true,
    "apiVersion": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "description": "Production webhook",
    "id": "whe_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "storeId": "str_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "subscribedEvents": [
      "product.created",
      "product.updated"
    ],
    "updatedAt": "2019-08-24T14:15:22Z",
    "url": "https://example.com/webhooks/mercel"
  },
  "secret": {
    "createdAt": "2019-08-24T14:15:22Z",
    "id": "whs_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "secret": "whsec_AAAA1111BBBB2222CCCC3333DDDD4444",
    "secretPreview": "whsec_AAA…"
  }
}

Update a webhook endpoint

Updates the specified webhook endpoint by setting the values of the fields passed. Any fields not provided are left unchanged.

Path & query parameters

endpointIdstringRequired

The id of the webhook endpoint to operate on.

Body parameters

activeboolean

Whether the endpoint should receive new deliveries. Disable to pause without losing the endpoint and its history.

apiVersionstring

Pinned event payload version. Reserved for forward compatibility.

descriptionstring

Optional human-readable label shown in the dashboard.

length ≤ 500
subscribedEventsarray of strings

Event types (or glob patterns) the endpoint subscribes to. Patterns are constrained to the published catalog — see GET /v1/webhooks/event-types.

urlurl

Absolute https URL the webhook events should be POSTed to.

curl -X PATCH "https://api.mercel.app/v1/webhooks/endpoints/whe_01hh9zzzzzzzzzzzzzzzzzzzzz" \  -H "Content-Type: application/json" \  -d '{}'
Response200
{
  "endpoint": {
    "active": true,
    "apiVersion": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "description": "Production webhook",
    "id": "whe_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "storeId": "str_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "subscribedEvents": [
      "product.created",
      "product.updated"
    ],
    "updatedAt": "2019-08-24T14:15:22Z",
    "url": "https://example.com/webhooks/mercel"
  }
}

Delete a webhook endpoint

Permanently deletes a webhook endpoint and revokes its signing secrets. Past delivery rows are retained for audit purposes. This action cannot be undone.

Path & query parameters

endpointIdstringRequired

The id of the webhook endpoint to operate on.

curl -X DELETE "https://api.mercel.app/v1/webhooks/endpoints/whe_01hh9zzzzzzzzzzzzzzzzzzzzz"
Response200
{
  "ok": true
}

List all webhook event types

Lists the published catalog of event types a webhook endpoint can subscribe to. The catalog is curated — subscriptions must match an entry exactly or use a documented glob pattern. The catalog is the same for every store.

Path & query parameters

limitinteger

Maximum number of items to return per page. Defaults to 20, capped at 100.

1 ≤ value ≤ 100
pagestring

Opaque pagination token. Pass the value returned in nextPageUrl / previousPageUrl rather than constructing one — the encoding is internal and may change.

curl -X GET "https://api.mercel.app/v1/webhooks/endpoints/event-types"
Response200
{
  "data": [
    {
      "category": "product",
      "description": "string",
      "type": "product.created"
    }
  ],
  "nextPageUrl": "http://example.com",
  "previousPageUrl": "http://example.com"
}

Rotate a webhook signing secret

Issues a fresh signing secret on the endpoint. The previous secret remains valid for 24 hours so receivers can roll over without missing deliveries. The new raw secret is returned exactly once.

Path & query parameters

endpointIdstringRequired

The id of the webhook endpoint to operate on.

curl -X POST "https://api.mercel.app/v1/webhooks/endpoints/whe_01hh9zzzzzzzzzzzzzzzzzzzzz/rotate-secret"
Response200
{
  "secret": {
    "createdAt": "2019-08-24T14:15:22Z",
    "id": "whs_01HJZQK7XJ8R9YGEWABCDEFGHJK",
    "secret": "whsec_AAAA1111BBBB2222CCCC3333DDDD4444",
    "secretPreview": "whsec_AAA…"
  }
}

Send a test event to a webhook endpoint

Enqueues a synthetic webhook.ping delivery to the endpoint so you can verify connectivity, signing, and your receiver code without waiting for a real event. The endpoint must be active.

Path & query parameters

endpointIdstringRequired

The id of the webhook endpoint to operate on.

curl -X POST "https://api.mercel.app/v1/webhooks/endpoints/whe_01hh9zzzzzzzzzzzzzzzzzzzzz/send-test-event"
Response202
{
  "ping": {
    "deliveryId": "whd_01HJZQK7XJ8R9YGEWABCDEFGHJK"
  }
}

On this page

The webhook endpoint objectList all webhook endpointsRetrieve a webhook endpointCreate a webhook endpointUpdate a webhook endpointDelete a webhook endpointList all webhook event typesRotate a webhook signing secretSend a test event to a webhook endpoint