Skip to main content
FormuleyFormuley

Webhooks

Subscribe to Formuley events, choose a safe endpoint, verify signatures, and troubleshoot deliveries.

Updated March 13, 2026
2 min read

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.

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

Related Docs

Developer

Authentication and scopes

Create API keys, use the correct bearer format, understand scopes, and interpret rate-limit and authorization failures.

Developer

Data sync and exports

Choose between bulk operations, raw data endpoints, and export jobs for migration, analytics, and downstream sync workflows.

Need a quick answer instead?

Open Help for troubleshooting, billing, account questions, and direct support routes. Stay in Docs when you need setup or workflow steps.

Open HelpContact the Team