# Flowg8 · Workflow webhooks

Receive selected workflow lifecycle events at your signed HTTPS endpoint.

Manage destinations in Organization → Webhooks using an administrator user token (Sandbox developers may manage their Sandbox). Configuration and secrets are separate per environment. Sandbox destinations make real HTTPS requests to your test receiver. Integration API keys cannot manage webhook destinations.

Events: run.started, gate.activated, gate.approved, gate.rejected, acknowledgment.requested, acknowledgment.completed, notification.created, notification.delivered, notification.failed, run.approved, run.rejected, run.completed, run.expired. Each payload has id, type, apiVersion, createdAt, sequence, organizationId, environment and data.run/data.gate/data.notification/data.outcome. The run includes id, referenceId, flowId and flowVersionId. Request fields and comments are not embedded; fetch details using the run API.

Verify Flowg8-Signature: t=<Unix seconds>,v1=<HMAC-SHA256 hex> over timestamp + "." + the unchanged raw HTTP body, using your fg_whsec_ secret. The SDK exports verifyWebhookSignature(rawBody, header, secret), enforcing a five-minute timestamp tolerance. A retry uses a fresh signature timestamp but the same event ID and payload. Deduplicate by event.id, accept out-of-order events, return 2xx promptly and process asynchronously.

Delivery is at least once, with up to ten automatic attempts within 72 hours. HTTPS/public destinations on port 443 only; private addresses and redirects are rejected. Delivery history is retained for up to 30 days, bounded by Sandbox data retention. Pausing prevents new messages and pauses queued messages; changing URL cancels pending deliveries rather than redirecting old events.

## GET /v1/webhook-endpoints

Authentication: FLOWG8_ACCESS_TOKEN from Flowg8 sign-in
Required tenant header: X-Organization-Id.
Required user permissions: Administrator or Sandbox developer required. The API checks current membership, roles, key scopes and resource permissions on every request. Documentation visibility grants no access.

## Request example (replace example IDs)

```sh
curl "https://api.flowg8.io/v1/webhook-endpoints" \
  -H "authorization: Bearer $FLOWG8_ACCESS_TOKEN" \
  -H "x-organization-id: 10000000-0000-4000-8000-000000000001"
```

## Response excerpt

```json
{
  "configured": true,
  "items": []
}
```

Source: /docs/webhooks
Full schemas: /docs/openapi.json