Webhook endpoints

A webhook endpoint is a URL you control, registered with Storlaunch, that receives HTTP POST notifications when state changes in your workspace. Use one per integration: order-fulfilment service, CRM mirror, analytics pipeline. Each endpoint carries its own signing secret so you can verify the event came from Storlaunch.

For the wire-level signature recipe, retry policy, and the catalogue of event types, see Webhooks.

All endpoints require an sk_* key.

Endpoints

Method	Path	Purpose
`POST`	`/v1/payment/webhook-endpoints`	Register a new endpoint
`GET`	`/v1/payment/webhook-endpoints`	List endpoints
`GET`	`/v1/payment/webhook-endpoints/:id`	Retrieve one
`PATCH`	`/v1/payment/webhook-endpoints/:id`	Update URL, events, or active state
`DELETE`	`/v1/payment/webhook-endpoints/:id`	Delete

Create

POST /v1/payment/webhook-endpoints

Tier-limited — some plans cap endpoint count. The signing secret is generated server-side and returned once on this response — stash it.

Request body

Field	Type	Required	Description
`url`	string (HTTPS)	yes	The HTTPS URL we POST events to. HTTP is rejected.
`events`	array of strings	no	Event types to subscribe to. Empty array = subscribe to everything. See Webhook events for the catalogue.
`description`	string (≤200)	no	Internal label.
`active`	boolean	no	Defaults `true`. `false` endpoints receive no deliveries but stay configured.

Response — 201 Created

{
  "data": {
    "id": "whe_01HX...",
    "url": "https://api.acme.com/webhooks/storlaunch",
    "events": ["product.purchased", "checkout.completed"],
    "description": "Order fulfilment hook",
    "active": true,
    "secret": "whsec_01HXabcdef0123456789...",
    "createdAt": "2026-05-13T10:42:00Z"
  },
  "error": null,
  "meta": { "requestId": "req_01HX...", "timestamp": "2026-05-13T10:42:00Z" }
}

secret is returned exactly once. Storlaunch stores it (we need it to sign deliveries), but list/retrieve endpoints return a redacted version. If you lose it, rotate the endpoint — PATCH with rotateSecret: true.

List / retrieve

Standard. The secret field on list/retrieve is redacted (whsec_***).

Update

PATCH /v1/payment/webhook-endpoints/:id

Field	Type	Description
`url`	string	Change the destination. Existing pending retries continue against the old URL until they exhaust.
`events`	array	Replace the event subscription.
`description`	string	Rename.
`active`	boolean	Pause or resume.
`rotateSecret`	boolean	If `true`, generates a new secret and returns it in the response. The old secret stops working immediately.

Delete

DELETE /v1/payment/webhook-endpoints/:id

Removes the endpoint. In-flight retries against this endpoint are dropped.

Auto-managed endpoints

Storlaunch automatically maintains two system-managed endpoints that you'll see in GET /webhook-endpoints but shouldn't modify:

`description`	URL	Purpose
`fulkruma.outbound`	`https://fulkruma.com/api/v1/webhooks/storlaunch`	Catalogue sync to Fulkruma when fulfilment module is on.
`ripllo.outbound`	`https://ripllo.com/api/v1/webhooks/storlaunch`	Product mirror to Ripllo for tag-scoped discount lookups.

Don't DELETE these — Storlaunch will recreate them on the next module-enable check, and any manual edits will drift. If you need to inspect what's flowing into them, query the Fulkruma / Ripllo side.

The webhook-endpoint object

Field	Type	Nullable	Description
`id`	string	no	`whe_` + ULID.
`accountId`	string	no	Workspace.
`url`	string	no	HTTPS destination.
`events`	array	no	Subscribed event types. Empty = all.
`description`	string	yes	Internal label.
`active`	boolean	no	Delivery enabled.
`secret`	string	no	Signing secret. Redacted on read endpoints after creation.
`createdAt` / `updatedAt`	string	no	Timestamps.

Delivery semantics

When an event fires, Storlaunch finds every matching endpoint and writes one WebhookEvent row per (event, endpoint) pair. A background delivery worker picks rows off the queue and POSTs to your URL:

POST body is the JSON-encoded event (see Webhooks).
Header X-Storlaunch-Signature carries the HMAC-SHA256 of the body keyed by your secret.
Header X-Storlaunch-Event-Id carries event.id — use it for idempotency on your end.
A 2xx response acknowledges. Anything else triggers retry with exponential backoff.
After 20 consecutive failures, Storlaunch disables the endpoint and fires webhook_endpoint.disabled to the other endpoints in the workspace.

webhook_endpoint.disabled is reserved but not emitted today. The auto-disable behaviour is implemented, but the cross-endpoint notification event isn't currently wired in the outbox. Monitor your endpoints via GET /webhook-endpoints for active: false until this ships.

Events

Event type	Fires on
(none)	—

Endpoint-lifecycle changes are logged in Audit log but don't fire webhook events themselves (that would be circular).

Webhooks — signature recipe, retry policy, ordering.
Webhook events — the full event catalogue.
API keys — the other side of the integration credential.