Overview

Webhooks let your integration receive real-time notifications when events occur in Caspeco. Instead of polling the API for changes, Caspeco sends a request to a URL you provide whenever a matching event is triggered.

How It Works

1. You register a webhook subscription with a target URL and the specific event (webhook definition) you want to subscribe to
2. When the event occurs in Caspeco, a request containing a JSON payload is sent to your URL
3. Your endpoint processes the payload and returns a 200 OK response

If your endpoint does not return a 2xx success status code, the delivery is considered failed and will be retried automatically up to 8 attempts with exponential back-off. Make sure your endpoint responds quickly — heavy processing should be done asynchronously after acknowledging receipt.

Webhook Definitions

Each webhook type is described by a webhook definition. A definition specifies:

Field	Description
Name	A unique identifier for the event type, e.g. Pos.Sale.V1
Description	What triggers the event
Origin	The scope the webhook fires for, e.g. LOCATION or COMPANY
Payload Schema	A JSON Schema describing the structure of the request body your endpoint will receive
Required Permissions	The API permissions your integration needs to subscribe to this event

Browse all available definitions under Reference → Webhooks in the sidebar.

Creating a Subscription

Webhook subscriptions are managed through the Integrations page. To create one you will need:

• A target URL — a publicly accessible HTTPS endpoint on your side
• The webhook definition ID of the event you want to subscribe to
• An Origin — the entity the subscription applies to, such as a location, company, organization, or brand
• Your dev partner ID

Choosing the Right Origin

An important part of creating a webhook subscription is choosing the correct Origin.

The Origin is the entity your webhook subscription is scoped to. When you create a subscription, the webhook delivery service compares each webhook message’s origin to the Origin you selected and delivers the message if it matches that entity or a supported descendant in the hierarchy.

The webhook delivery service uses the following rules:

1. If the message origin is the same entity as the selected Origin, the message is delivered.
2. Otherwise, the webhook delivery service checks whether the message origin is a descendant of the selected Origin in the Organizations hierarchy.

In practice, you should choose the highest-level Origin that matches the scope you want:

If you want events for…	Use this Origin
One specific location	Select that location as the Origin
All locations and areas in one company	Select that company as the Origin
All companies, locations, and areas in one organization	Select that organization as the Origin
All locations and areas connected to one brand	Select that brand as the Origin

How Hierarchy Matching Works

The webhook delivery service resolves parent/child relationships in the Organizations hierarchy when matching webhook messages to subscriptions.

For an overview of the organizational structure used in this hierarchy, see the Organizations overview.

The following parent scopes can include these descendants:

• ORGANIZATION → COMPANY, LOCATION, AREA
• COMPANY → LOCATION, AREA
• LOCATION → AREA
• BRAND → LOCATION, AREA
• AREA → child areas in the same area tree

Some relationships are intentionally not expanded. For example, an ORGANIZATION subscription does not automatically match BRAND origins.

If you are unsure which Origin to use, start from the scope you want to monitor and choose the entity at that level rather than one of its children.

Payload Structure

Every webhook payload conforms to the JSON Schema defined on the webhook definition. Your endpoint will receive a request with Content-Type: application/json.

Always validate the payload against the schema before processing it, and return 200 OK as quickly as possible.

Securing Your Endpoint

Every request from Caspeco includes an X-CASPECO-SIGNATURE header containing an HMAC-SHA256 signature. You should validate this on every incoming request to ensure it genuinely comes from Caspeco. See the Securing Webhooks guide for details.

Available Events

Browse all available webhook definitions under Reference → Webhooks in the sidebar.