Webhooks

Use a project key with webhooks:manage. Register an HTTPS endpoint through the public gateway:

curl "https://apis.cloud.feeef.org/v1/webhook-endpoints" \
  -H "Authorization: Bearer $FEEEF_CLOUD_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-service.example/cloud-events","events":["ai.task.completed","ai.task.failed","ai.task.reconciliation_required"]}'

Save the returned data.secret securely: it is returned once. Do not use a provider API key as the webhook secret. Inspect endpoint delivery logs when callbacks fail.

Supported event families:

• AI: ai.task.completed, ai.task.failed, ai.task.reconciliation_required.
• Parcels: parcel.created, parcel.status_changed, parcel.delivered, parcel.deleted, batch.completed.
• Inventory: inventory.stock.changed, inventory.reservation.expired, inventory.operation.posted.

events must be a nonempty supported list, or ["*"]. Inventory endpoints can also use topic patterns.

Verify before parsing

Read X-Feeef-Cloud-Signature as t=<unix-seconds>,v1=<hex-signature>. Compute HMAC-SHA256 of the timestamp, a dot, and the exact raw request body, using the endpoint secret. Compare equal-length signatures in constant time and reject timestamps outside a five-minute tolerance. Verify before parsing JSON; re-serializing an object changes the signed bytes.

Other headers are X-Feeef-Cloud-Id, X-Feeef-Cloud-Type, X-Feeef-Cloud-Timestamp and X-Feeef-Cloud-Delivery. Delivery is at least once: deduplicate the event ID durably and acknowledge promptly after recording it. A callback is a notification; fetch the task with the owning project's credential for its result and billing.

Per-request arbitrary callback URLs are not accepted for AI. Register your endpoint first, then subscribe to task events.