API v1

Webhook Endpoint API

Webhook endpoint APIs manage beta outbound platform webhooks. These are different from inbound workflow trigger URLs. Outbound deliveries are signed and can be tested, inspected, retried, rotated, or deleted.

Step 1

Create an HTTPS receiver endpoint with subscribed event types.

Step 2

Send a test delivery and verify signature handling in your receiver.

Step 3

Inspect deliveries, retry failures, and rotate signing secrets when ownership changes.

Endpoints

GET/api/v1/webhook-endpoints?limit=10

List outbound webhook endpoints and delivery health metadata.

Required scope: webhooks:read

curl https://www.finkmesh.com/api/v1/webhook-endpoints?limit=10 \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

{
  "data": [
    {
      "id": "wh_123",
      "name": "Production webhooks",
      "url": "https://example.com/finkmesh/webhooks",
      "status": "active",
      "events": ["workflow.run.completed"]
    }
  ],
  "pagination": { "limit": 10, "hasMore": false, "nextCursor": null },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

POST/api/v1/webhook-endpointsIdempotency-Key

Create an outbound webhook endpoint. The full signing secret is returned once.

Required scope: webhooks:write

curl -X POST https://www.finkmesh.com/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: webhook-create-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production webhooks","url":"https://example.com/finkmesh/webhooks","events":["workflow.run.completed"]}'

{
  "data": {
    "id": "wh_123",
    "status": "active",
    "secret": "whsec_..."
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

GET/api/v1/webhook-endpoints/{endpointId}

Fetch one endpoint and its health metadata without returning the signing secret.

Required scope: webhooks:read

curl https://www.finkmesh.com/api/v1/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

{
  "data": {
    "id": "wh_123",
    "name": "Production webhooks",
    "status": "active",
    "secretPreview": "whsec_abc...xyz123"
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

PATCH/api/v1/webhook-endpoints/{endpointId}Idempotency-Key

Update endpoint name, URL, subscribed events, or active status.

Required scope: webhooks:write

curl -X PATCH https://www.finkmesh.com/api/v1/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: webhook-update-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production webhooks","events":["workflow.run.completed"],"status":"active"}'

{
  "data": {
    "id": "wh_123",
    "name": "Production webhooks",
    "status": "active"
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

DELETE/api/v1/webhook-endpoints/{endpointId}Idempotency-Key

Delete an outbound webhook endpoint and stop future deliveries for that subscription.

Required scope: webhooks:write

curl -X DELETE https://www.finkmesh.com/api/v1/webhook-endpoints/{endpointId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: webhook-delete-$(uuidgen)"

{
  "data": {
    "deleted": true,
    "id": "wh_123"
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

POST/api/v1/webhook-endpoints/{endpointId}/rotate-secretIdempotency-Key

Rotate the endpoint signing secret. The new full secret is returned once.

Required scope: webhooks:write

curl -X POST https://www.finkmesh.com/api/v1/webhook-endpoints/{endpointId}/rotate-secret \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: webhook-rotate-$(uuidgen)"

{
  "data": {
    "id": "wh_123",
    "secret": "whsec_..."
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

POST/api/v1/webhook-endpoints/{endpointId}/testIdempotency-Key

Queue a signed workflow.run.completed test delivery. The API returns current delivery status; slow receivers may start as pending or delivering, so poll the delivery endpoint for final status.

Required scope: webhooks:write

curl -X POST https://www.finkmesh.com/api/v1/webhook-endpoints/{endpointId}/test \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: webhook-test-$(uuidgen)"

{
  "data": {
    "eventId": "evt_123",
    "deliveryId": "del_123",
    "status": "succeeded"
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

GET/api/v1/webhook-endpoints/{endpointId}/deliveries

List recent delivery attempts for one outbound endpoint.

Required scope: webhooks:read

curl https://www.finkmesh.com/api/v1/webhook-endpoints/{endpointId}/deliveries \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

{
  "data": [
    {
      "id": "del_123",
      "eventType": "workflow.run.completed",
      "status": "succeeded",
      "responseStatus": 200
    }
  ],
  "pagination": { "limit": 50, "hasMore": false, "nextCursor": null },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

GET/api/v1/webhook-deliveries/{deliveryId}

Fetch one outbound webhook delivery with request/response metadata.

Required scope: webhooks:read

curl https://www.finkmesh.com/api/v1/webhook-deliveries/{deliveryId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

{
  "data": {
    "id": "del_123",
    "eventId": "evt_123",
    "eventType": "workflow.run.completed",
    "status": "succeeded",
    "responseStatus": 200
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

POST/api/v1/webhook-deliveries/{deliveryId}/retryIdempotency-Key

Retry a failed or dead delivery immediately.

Required scope: webhooks:write

curl -X POST https://www.finkmesh.com/api/v1/webhook-deliveries/{deliveryId}/retry \
  -H "Authorization: Bearer $FINKMESH_TOKEN" \
  -H "Idempotency-Key: webhook-retry-$(uuidgen)"

{
  "data": {
    "id": "del_123",
    "status": "pending",
    "attempts": 2
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

Signing

Delivery signatures use HMAC-SHA256 over timestamp.eventId.rawBody and should be verified with timestamp tolerance.

Retries

Failed deliveries retry with exponential backoff and become dead after delivery attempts are exhausted. Manual retry is available by API.

Related Docs

Outbound Webhook Docs Rate Limits