Webhooks

Overview

Webhooks let Formuley push outbound events to your application instead of forcing you to poll the API continuously.

Manage webhook endpoints from /developer/webhooks or through the REST API under /api/v1/webhooks.

Webhook management requires Business or higher. In an organization, the user also needs integration-admin permission to create, update, rotate the secret for, or delete organization-managed endpoints. Organization members with integration read access can send a test delivery for an endpoint they can view, but that access does not let them change the endpoint.

What you can subscribe to

Current event types in code include:

• formula.created
• formula.updated
• formula.deleted
• ingredient.created
• ingredient.updated
• ingredient.deleted
• ingredient.low_stock
• batch.created
• batch.updated
• batch.completed
• order.created
• order.updated
• compliance.check_completed

The webhook test route also sends a test.ping event when you trigger a test delivery.

Endpoint requirements

For real integrations, use a public HTTPS endpoint you control.

The delivery system rejects private, internal, and non-HTTPS destinations. The create and test flows both expect resolvable public HTTPS URLs.

Signature verification

Deliveries include these headers:

X-Formuley-Signature: sha256=...
X-Formuley-Event: formula.created
X-Formuley-Delivery: <delivery-id>

Verify the signature with your webhook secret and the raw request body before processing the payload.

Delivery behavior

The REST API includes:

• /api/v1/webhooks to create and list endpoints
• /api/v1/webhooks/[id] to read, update, or delete a webhook
• /api/v1/webhooks/[id]/test to send a test event
• /api/v1/webhooks/[id]/deliveries to inspect delivery history

Use the delivery history first when debugging failures.

Operational recommendations

• Use one endpoint per environment.
• Keep handlers idempotent.
• Log payloads and response codes during initial setup.
• Start with a narrow event set and expand once the integration is stable.

Troubleshooting

• If the endpoint never receives test traffic, confirm the URL is public and reachable.
• If signature verification fails, hash the raw request body rather than a parsed or re-serialized version.
• If you see duplicate effects, store delivery or event identifiers and make processing idempotent.

Next docs

• Authentication and scopes
• Data sync and exports