Webhooks

Webhooks are backend-to-backend HTTPS callbacks from flinkey to your backend. They deliver asynchronous operation results — especially for assignment operations. Assignment creation, update and deletion must not be treated as final until the corresponding webhook result has been processed.

Setup

Configure your webhook endpoint in the flinkey Portal (Developer → API section).

Recommended endpoint structure:

POST https://your-backend.example.com/webhooks/flinkey/assignments

Transport requirements

Requirement	Detail
Protocol	HTTPS with valid SSL certificate
Method	HTTP `POST`
Content type	`application/json`
Response	`200 OK` or `204 No Content` after successful processing

Reject unsupported methods and malformed payloads.

Webhook secret

A webhook secret can be configured in the flinkey Portal. If configured, flinkey sends it with each request:

secret: <your_webhook_secret>

Situation	Action
Secret configured, header matches	Accept and process
Secret configured, header missing	Reject (`401` or `403`)
Secret configured, header invalid	Reject (`401` or `403`)
Secret not configured	Process only if intentional

Assignment webhook results

The core webhook events correspond to assignment operations:

Webhook result	Related API operation
Assignment created result	`PUT /assignments`
Assignment updated result	`PATCH /assignments/{assignmentId}`
Assignment deleted result	`DELETE /assignments/{assignmentId}`

Processing flow

sequenceDiagram
    autonumber
    participant flinkey
    participant webhook as Partner webhook
    participant backend as Partner backend
    participant db as Database

    flinkey->>webhook: POST assignment result
    webhook->>webhook: Validate secret header
    webhook->>webhook: Validate payload
    webhook->>backend: Resolve local assignment
    backend->>db: Persist webhook event
    backend->>db: Update assignment state
    backend-->>webhook: Event accepted
    webhook-->>flinkey: 200 OK

Created result

Key fields in the webhook payload:

Field	Description
`checksum`	Correlation value from the initial request
`assignmentId`	flinkey assignment ID (`null` if creation failed)
`carId`	Car the assignment refers to
`userId`	User the assignment refers to
`operationSucceeded`	Whether the operation succeeded
`errorMessage`	Error detail if failed
`start` / `end`	Assignment time window

If operationSucceeded = true → mark assignment as active. If operationSucceeded = false → mark as failed, store the error message.

Updated result

Key fields: checksum, assignmentId, operationSucceeded, errorMessage, updateData (list of patch operations).

Deleted result

Key fields: checksum, assignmentId, operationSucceeded, errorMessage.

Idempotency

Webhook processing must be idempotent — the same event may arrive more than once.

Recommended idempotency anchors: assignmentId, checksum, operation type, customerId.

Situation	Handling
Same successful event received twice	Keep final state unchanged
Failed event received twice	Do not create duplicate incidents
Webhook arrives before local state exists	Store event, reconcile later
Webhook for unknown assignment	Store as unresolved, investigate
Invalid webhook secret	Reject, do not process

Error handling

Distinguish technical errors (invalid secret, bad JSON, DB unavailable) from business failures (operationSucceeded = false).

Reject invalid requests immediately.
Persist unresolved events for investigation.
Alert on repeated processing failures.
For business failures: persist the result, mark the operation as failed, surface to operations.

Monitoring

Recommended monitoring signals:

Webhook request / success / error count
Invalid secret count
Business failure count
Processing latency
Last received / last failed timestamp
Unresolved webhook count

Set alerts for repeated processing failures.

Recommended HTTP responses

Situation	Response
Event accepted and persisted	`200 OK` or `204 No Content`
Invalid secret	`401 Unauthorized` or `403 Forbidden`
Invalid payload	`400 Bad Request`
Temporary backend failure	`5xx`