FlowynBETA
LoginSign up

Integrations and endpoints

Creates an HTTPS destination for chosen event types, returns its signing secret once, and sends test deliveries whose results are recorded.

What integrations and endpoints does

Creates an HTTPS destination for chosen event types, returns its signing secret once, and sends test deliveries whose results are recorded.

When to use integrations and endpoints

  • Connecting a partner system
  • Validating a new receiver
  • Staging before live

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/endpoints

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/endpoints \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ep-orders" \
  -d '{
    "name": "Orders destination",
    "url": "https://hooks.example.com/orders",
    "event_types": [
      "order.completed"
    ]
  }'

Response

Flowyn returns HTTP 200. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "5f9b2d7e-3a1c-4d6f-8b0e-4c2a9e7d1f38",
  "environment": "test",
  "name": "Orders destination",
  "url": "https://hooks.example.com/orders",
  "event_types": [
    "order.completed"
  ],
  "disabled": false,
  "signing_secret": "whsec_•••• (shown once)",
  "signing_secret_hint": "whsec_…a1b2"
}

Lifecycle

  1. Create the endpoint. signing_secret is returned once; store it.
  2. POST /v1/endpoints/{id}/test sends a test delivery and records its result.
  3. Events whose type is in event_types are delivered to the endpoint.
  4. Rotate the secret with POST /v1/endpoints/{id}/rotate-secret, or disable the endpoint to stop deliveries without deleting history.

Status values

StatusMeaning
enabled (disabled: false)Receives deliveries.
disabled (disabled: true)Kept, receives no deliveries.

Retries

Deliveries to the endpoint follow the event retry policy.

Idempotency

Send Idempotency-Key on create.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • HTTPS URLs only
  • timeout_ms 100–30,000
  • Optional max_sends_per_minute 1–600

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/endpoints/5f9b2d7e-3a1c-4d6f-8b0e-4c2a9e7d1f38 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

Watch the receiver itself with Monitors.