BioFlow / API docs / createWebhookEndpoint

Create a webhook endpoint.

POST /v1/webhook-endpoints

scope: webhooks:writeCreator & Pro plansquota cost: 1send an Idempotency-Key

Register a public HTTPS URL for event delivery. The URL is SSRF-screened, then must accept a SIGNED endpoint.test event with 2xx before anything is stored. The response carries the whsec_ signing secret exactly once. Deliveries are signed per Standard Webhooks (webhook-id / webhook-timestamp / webhook-signature over `id.timestamp.rawBody`), retried with exponential backoff for ~41 hours, and the endpoint auto-disables after 20 consecutive failures.

Requires scope: webhooks:write. Plan entitlement: public_api (Creator and Pro).

Consequential operation — send an Idempotency-Key header.

Open in Claude ↗Open in ChatGPT ↗

Try it

Request.

curl "https://app.getbioflow.com/v1/webhook-endpoints" \
  -X POST \
  -H "Authorization: Bearer bf_live_YOUR_KEY" \
  -H "Idempotency-Key: a-unique-id-per-attempt" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/bioflow",
    "event_types": [
      "contact.created"
    ]
  }'

Request body

JSON body (application/json).

Request-body fields for createWebhookEndpoint
Field	Type	Required	Description
`url`	string	yes	Public HTTPS URL on port 443. Verified with a signed endpoint.test event before the endpoint is created — respond 2xx.
`event_types`	array<contact.created \| page.published \| sale.paid \| sale.refunded>	yes	—

Response

201 — The created endpoint and its signing secret (shown once).

Fields of the 201 response for createWebhookEndpoint
Field	Type	Description
`endpoint`	object	—
`secret`	string	The whsec_ signing secret — shown ONCE, store it now. Verify webhook-signature with it per Standard Webhooks.

Every response also carries X-Request-Id plus the IETF draft-11 RateLimit / RateLimit-Policy headers.

Errors

What can go wrong here.

Problem codes this operation can return
Code	Status	Meaning
`invalid_request`	400	The request body or parameters failed validation
`invalid_api_key`	401	Missing, malformed, unknown, disabled, or expired API key
`insufficient_scope`	403	The API key was not granted the required scope
`feature_not_enabled`	403	The workspace plan does not include public API access
`test_key_read_only`	403	Test-mode keys are restricted to read operations
`rate_limited`	429	Per-key rate limit exceeded
`quota_exhausted`	429	Monthly API quota exhausted
`internal_error`	500	Something went wrong on our side

All errors are RFC 9457 application/problem+json — branch on code, quote request_id to support. Full registry on the API docs hub; interactive playground in the API reference.