# Public webhook API

A workspace can expose a published workflow through a generic webhook trigger. The flow builder supplies the trigger's public ID and secret.

## Start a run

```bash
curl -X POST "https://your-domain.example/api/v1/webhooks/PUBLIC_ID" \
  -H "Authorization: Bearer WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: order-1234" \
  -d '{"customer_id": 42, "event": "order.created"}'
```

The secret may instead be sent in `X-JustFlows-Webhook-Secret`. A valid request returns HTTP `202` with the flow run ID, trigger event ID, current status, and a `run_status_url`.

## Read run status

```bash
curl "https://your-domain.example/api/v1/webhooks/PUBLIC_ID/runs/RUN_ID" \
  -H "X-JustFlows-Webhook-Secret: WEBHOOK_SECRET"
```

| Status | Meaning |
| --- | --- |
| `200` | The requested run belongs to this webhook and its status was returned. |
| `202` | The webhook was accepted and the run was started. |
| `401` | The webhook secret is missing or invalid. |
| `404` | The trigger is missing/inactive, or the run does not belong to it. |
| `422` | The event was received but a workflow run could not be started. |

- Store the secret in a secret manager and rotate it if exposed.
- Use a stable, unique `X-Request-Id` for tracing.
- Treat `202` as asynchronous acceptance, not completed work.
- Set upstream timeouts and retries appropriate for an asynchronous endpoint.
- Deactivate the trigger before deleting or replacing an external integration.