Webhooks

Webhooks overview

Receive signed events when API or MCP operations complete and when important usage or library events occur.

Verified against the implementation · 2026-09-09

Create an endpoint

Create endpoints in Workspace → API & MCP → Webhooks or through POST /webhook-endpoints with the webhooks:manage scope. URLs must use HTTPS and resolve to a public host.

curl -X POST https://api.promptessor.com/v1/webhook-endpoints \
  -H "Authorization: Bearer pt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/promptessor",
    "description": "Production event receiver",
    "events": ["operation.succeeded", "operation.failed"]
  }'

Copy the secret once

The whsec_ signing secret is returned only when the endpoint is created or rotated. Store it securely before closing the response or dashboard dialog.

Endpoint management

Method	Path	Purpose
GET	/webhook-endpoints	List owned endpoints
POST	/webhook-endpoints	Create an endpoint and return its secret once
GET	/webhook-endpoints/{id}	Read one endpoint
PATCH	/webhook-endpoints/{id}	Update URL, description, events, enabled state, or rotate the secret
POST	/webhook-endpoints/{id}	Send a dedicated webhook.test event
DELETE	/webhook-endpoints/{id}	Delete the endpoint

To rotate a secret, PATCH the endpoint with rotateSecret: true. The previous secret stops working immediately.

Receiver requirements

Accept HTTPS POST requests with application/json.
Read and verify the signature against the raw request body before parsing JSON.
Return any 2xx response within 10 seconds.
Do not redirect webhook requests.
Deduplicate using x-promptessor-delivery or the payload event id.
Queue business processing and respond quickly instead of doing slow work inline.