Webhooks

Create, list, update, and delete webhooks for your store. Maximum 20 webhooks per store.

List Webhooks

GET/api/v1/webhooks

Permission required: webhooks:read

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Number of results per page. Range: 1–50.
`page`	integer	`1`	Page number for pagination. Min: 1.
`sort_field`	string	`created_at`	Field to sort by. Options: `created_at`, `updated_at`.
`sort_order`	string	`DESC`	Sort direction. Options: `ASC`, `DESC`.

Example Request

cURL

curl -X GET "https://api.storeep.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

200 OK

{
    "data": [
        {
            "id": 298437652918374561,
            "name": "Order notifications",
            "type": "api",
            "event": "order-created",
            "format": "json",
            "url_or_email": "example.com/webhooks/orders",
            "is_enabled": true,
            "created_at": "2025-01-15 10:30:00",
            "updated_at": "2025-01-15 10:30:00"
        }
    ],
    "meta": {
        "pagination": {
            "total": 3,
            "count": 3,
            "per_page": 20,
            "current_page": 1,
            "total_pages": 1,
            "links": {
                "next": null
            }
        }
    }
}

Response Fields

Field	Type	Description
`id`	integer	Unique webhook identifier.
`name`	string	Webhook name.
`type`	string	Delivery type: `api` or `e-mail`.
`event`	string	Trigger event: `session-created`, `order-created`, or `order-updated`.
`format`	string	Payload format: `json`.
`url_or_email`	string	Destination URL (for API type) or email address (for e-mail type).
`is_enabled`	boolean	Whether the webhook is active.
`created_at`	string	Creation timestamp (UTC).
`updated_at`	string	Last update timestamp (UTC).

Create Webhook

POST/api/v1/webhooks

Permission required: webhooks:write

Limit: Maximum 20 webhooks per store. Creating beyond this limit returns a 422 error.

Request Body (JSON)

Field	Type	Required	Description
`name`	string	Yes	Webhook name. Max 50 characters.
`type`	string	Yes	Delivery type: `api` or `e-mail`.
`event`	string	Yes	Trigger event: `session-created`, `order-created`, or `order-updated`.
`format`	string	Yes	Payload format: `json`.
`url_or_email`	string	Yes	Destination URL (max 500 chars) or email (max 127 chars) depending on type. URLs may contain `{{placeholder}}` tokens (e.g. `{{order_total}}`, `{{fbclid}}`) that will be replaced with event data values at delivery time.
`is_enabled`	boolean	No	Whether the webhook is active. Defaults to `true`.

Example Request

cURL

curl -X POST "https://api.storeep.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order notifications",
    "type": "api",
    "event": "order-created",
    "format": "json",
    "url_or_email": "example.com/webhooks/orders",
    "is_enabled": true
}'

Response

201 Created

{
    "status": "success",
    "data": {
        "id": 298437652918374561
    }
}

Update Webhook

PUT/api/v1/webhooks?id={webhook_id}

Permission required: webhooks:write

Send only the fields you want to update. All fields are optional.

Request Body (JSON)

Field	Type	Description
`name`	string	New webhook name. Max 50 characters.
`event`	string	New trigger event.
`url_or_email`	string	New destination URL or email.
`is_enabled`	boolean	Enable or disable the webhook.

Example Request

cURL

curl -X PUT "https://api.storeep.com/v1/webhooks?id=298437652918374561" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'

Response

200 OK

{
    "status": "success"
}

Delete Webhook

DELETE/api/v1/webhooks?id={webhook_id}

Permission required: webhooks:write

Example Request

cURL

curl -X DELETE "https://api.storeep.com/v1/webhooks?id=298437652918374561" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

200 OK

{
    "status": "success"
}

Error Responses

Status	Error	Cause
`403`	`insufficient permissions`	Token lacks `webhooks:read` or `webhooks:write`.
`404`	`webhook not found`	Webhook ID does not exist or does not belong to your store.
`422`	`maximum of 20 webhooks per store reached`	Store already has 20 webhooks. Delete one before creating another.
`422`	Field-specific errors	Invalid input, see the `errors` object for details.
`405`	`method not allowed`	Used an unsupported HTTP method.