Receive signed webhooks

Register a URL and Flowion POSTs a signed JSON body to it as things happen: a session starts or ends, a charger connects or goes offline, an outlet changes state. No polling, and every delivery is signed so you can prove it came from Flowion.

Add an endpoint

In the console, open a project, then Settings → Webhooks → Add endpoint. Give a URL and pick the events you want. The console creates the signing secret in your browser and shows it once.

Over the API you choose the secret yourself, at least 32 characters:

curl -X POST "$API/projects/$PROJECT/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetUrl": "https://api.example.com/flowion/webhooks",
       "eventTypes": ["transaction.started", "transaction.ended"],
       "signingSecret": "'"$(openssl rand -base64 32)"'"}'

{
  "id": "0c9b7f2e-6a41-4d8e-9b35-1f7a2c4e8d60",
  "projectId": "6f1d6b2c-6f0e-4a5a-9a9e-2b3c4d5e6f70",
  "targetUrl": "https://api.example.com/flowion/webhooks",
  "eventTypes": ["transaction.started", "transaction.ended"],
  "mode": "live",
  "state": "active",
  "createdAt": "2026-10-01T09:30:00Z",
  "updatedAt": "2026-10-01T09:30:00Z"
}

Adding, testing and changing endpoints needs the webhook.subscription.manage permission; listing them and their deliveries needs webhook.subscription.read.

An endpoint receives one mode's events. Registered with a sandbox API key, it gets sandbox events; with a live key, live events. mode says which.

The URL must be https and resolve to a public address. Flowion checks that on every delivery, not only when you register, so a hostname that later points inside your network shows up as blocked_address in the delivery history.

Send a test

In the console, choose Send a test on the endpoint. Over the API:

curl -X POST "$API/projects/$PROJECT/webhooks/$WEBHOOK/test" \
  -H "Authorization: Bearer $TOKEN"

{
  "sequence": 41802
}

A real delivery follows within moments — signed the same way, with the same headers and retries — as the event type webhook.test. Use it to check your signature verification before you wait for a real charge. webhook.test never fires your real handlers, and you cannot subscribe to it.

Verify the signature

Every delivery carries these headers:

The signature is HMAC-SHA256, keyed with your signing secret, over the timestamp, a full stop and the raw request body:

{X-Flowion-Timestamp}.{raw request body}

import hashlib, hmac, time

def verify(secret: str, timestamp: str, body: bytes,
           signature: str, tolerance: int = 300) -> bool:
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    signed = timestamp.encode() + b"." + body
    expected = "v1=" + hmac.new(
        secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

• Hash the bytes you received, before parsing the JSON. Parsing and re-serialising can reorder fields and break a valid signature.

• Compare in constant time, as compare_digest does.

• Reject old timestamps. The timestamp is signed, so checking it is what stops someone replaying a captured request. The five minutes above is an example; pick what suits you.

Answer fast, and expect repeats

• Reply with any 2xx within 10 seconds, then do the work. Anything else, a timeout included, is a failed attempt.

• Deduplicate on sequence. Delivery is at least once, so the same event can arrive twice.

• Order by occurred_at, not by arrival.

A failed delivery is retried, up to 16 attempts over 72 hours. Each retry is signed afresh, with a new timestamp.

When an endpoint runs out of retries, it moves to failing and Flowion stops sending to it. Fix the receiver, then:

• Reactivate the endpoint to resume new deliveries: POST /projects/{projectId}/webhooks/{subscriptionId}/reactivate.

• Replay each delivery that gave up (abandoned) to send it once more: POST /projects/{projectId}/webhooks/{subscriptionId}/deliveries/{sequence}/replay.

Both are buttons on the endpoint in the console too.

Rotate the secret

curl -X POST "$API/projects/$PROJECT/webhooks/$WEBHOOK/rotate-secret" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signingSecret": "'"$NEW_SECRET"'"}'

The new secret signs every delivery from the moment the call succeeds; the old one signs nothing more.

When nothing arrives

Open the endpoint's Recent deliveries in the console, or:

curl "$API/projects/$PROJECT/webhooks/$WEBHOOK/deliveries" \
  -H "Authorization: Bearer $TOKEN"

Each delivery shows its last outcome (lastOutcome), the exact body that was signed and sent (requestBody) and the start of your reply (responseBody):

An empty list means no event you subscribed to has happened in this project yet: a delivery is created when a matching event occurs. Check the events you picked. Event types marked Coming soon below are on their way.

Event reference