Skip to main content

Webhooks

Webhooks let your app talk to the rest of the internet in both directions. Outgoing webhooks notify an external URL whenever records in your database change, and incoming webhooks let external services trigger code in your app. This page covers configuring both, the payload and signature details, and how retries and failures are handled.

You might use outgoing webhooks to push new orders into a fulfillment tool or ping a team chat when someone signs up, and incoming webhooks to react when a connected service reports an event.

Outgoing webhooks​

Outgoing webhooks fire when data changes in your app's database. Configure them in Instroc Cloud, then Webhooks: pick a table, choose which events you care about (insert, update, delete), and give a destination URL. From then on, every matching change sends an HTTP POST to that URL.

Payload​

Each delivery is a JSON body describing what happened:

{
  "webhook_id": "wh_abc123",
  "event": "update",
  "table": "orders",
  "timestamp": "2026-08-16T10:30:00Z",
  "data": {
    "record": { "id": 42, "status": "shipped" },
    "old_record": { "id": 42, "status": "pending" }
  }
}

record is the row after the change, and old_record is the row before it (present on updates and deletes). The receiving service can use event and table to route the message and the two records to see exactly what changed.

Signatures​

If you set a secret on the webhook, every delivery includes an X-Webhook-Signature header containing an HMAC SHA-256 signature of the payload, computed with that secret. Verifying it on the receiving end proves the request really came from your app and was not tampered with. Use a secret for anything that triggers real-world actions.

Retries, logs, and auto-disable​

Deliveries are not fire-and-forget. If the destination does not respond successfully, Instroc retries up to 3 times with increasing backoff between attempts. Every attempt is recorded in the delivery logs in the Webhooks panel, so you can see what was sent, when, and how the receiver responded.

If a webhook fails 10 times in a row, it is automatically disabled so a dead endpoint does not keep consuming attempts. Fix the destination, then re-enable the webhook from the panel.

tip

Outgoing webhooks are the reliable way to react to data changes from outside your app. If instead you want to run your own code inside Instroc when something happens, an API route or function that performs the write and the follow-up action together is often simpler. See API routes and functions.

Incoming webhooks​

Your app can also receive webhooks from external services, in two ways.

Webhook-triggered functions​

Create a serverless function with the webhook trigger in the Functions panel, and it gets its own POST endpoint. External services post to that URL and the function runs with the delivered payload. You can optionally validate a signature so only the genuine sender can trigger it. Function details live in the Functions API reference.

File-based handlers​

For handlers that live in your project's code, create a file under the webhook/ folder. The file path becomes the endpoint on your published app:

  • webhook/stripe.ts handles POST /webhook/stripe

Handlers receive the same kind of ctx object as API routes, plus ctx.verifySignature(secret) for checking the sender's signature before trusting the payload. This is the right place for services that need a custom endpoint in your app's own domain.

caution

Stripe payment webhooks are the one case where you should never build a handler yourself. The platform processes them automatically: confirmed payments land in your app's private payments table without any webhook code on your side. See the Stripe integration.

Choosing the right tool​

As a quick guide: use outgoing webhooks to tell other systems about your data, webhook-triggered functions when a service just needs a URL to notify, and file-based handlers when the endpoint should live in your app's code with full database and storage access. And for payments, let the platform do the work.