DocumentationProduction
Open console
Docs/Signed Delivery Webhooks
INTEGRATE

Signed Delivery Webhooks

Consume workflow completion without trusting an unsigned callback.

Create a server-only delivery subscription

Use a workspace administrator or an API key with workflow-delivery:manage to register an HTTPS callback for the intended project. Midfleet returns the signing secret once; store it in a secret manager and rotate the subscription when ownership changes.

bash
curl -fsS -X POST \
  "$MIDFLEET_API/api/v1/projects/$MIDFLEET_PROJECT_ID/workflow/delivery-subscriptions" \
  -H "X-API-Key: $MIDFLEET_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"callback_url":"https://example.com/midfleet/delivery"}'

Verify before processing

  • Read the exact request body as bytes before JSON parsing.
  • Reject stale X-Midfleet-Timestamp values according to your replay window.
  • Verify X-Midfleet-Signature with the stored signing secret and a constant-time comparison.
  • Deduplicate X-Midfleet-Delivery-ID before causing side effects.
  • Validate workspace, project, invocation, run, artifact schema, version, and provenance before accepting the result.
  • Return a non-2xx response when the delivery should be retried.

Use the verifier example

The signed delivery example includes a small verifier and replay-window tests. Keep the verifier inside a server route; never expose the signing secret to browser code.