Webhooks · Documentatie · SAPUGO Community

A webhook tells another system about changes in SAPUGO. Whenever a record in one of the chosen tables is created, updated, or deleted, SAPUGO sends an HTTP POST with the details to an address you choose. Each request is signed, so the receiver can check that it really came from you.

Use a webhook to keep another system in step with every change, such as a data warehouse, a shop, or your own service.

Webhook or workflow#

You need	Use
Tell another system about every change to a table, as it happens	A webhook
Call another system only in some cases, or with a payload in its own format	A workflow with an HTTP step
Stop a bad record from being saved	A validation or guard

A webhook fires after the record has been saved, so it can't refuse or change a save.

Create a webhook#

Open Settings, choose Developer Tools, then Webhooks.
Click New webhook.
Enter a Name, such as "Customer sync", and optionally a description.
Enter the Target URL that should receive the requests. It must be reachable from the internet and use HTTPS. Private and local network addresses are rejected.
Pick the Database, then the Tables whose changes should be sent, up to twenty.
Under Events, choose CREATE, UPDATE, DELETE, or All events.
Make sure Active is on, and save.
Copy the signing secret from Save your signing secret and store it with your receiver. It's shown only once.

The signing secret is never shown again after you close that window. If you lose it, use Rotate to create a new one.

To try it out, click Test, choose the Table to test, and click Send test event. The test request has a placeholder record with test set to true, so your receiver can tell it apart from real changes.

What SAPUGO sends#

Each change is sent as a POST request with a JSON body.

{
  "event_id": "4f1c2d3e-…",
  "event_type": "UPDATE",
  "timestamp": 1760356800000,
  "org_id": "…",
  "database_id": "…",
  "table_id": "…",
  "table_name": "customers",
  "row_id": "…",
  "field_name": "status",
  "old_value": "lead",
  "new_value": "customer",
  "new_row": { "_id": "…", "name": "Acme Ltd", "status": "customer" },
  "created_by": "…",
  "subscription_id": "…",
  "delivery_id": "…",
  "resend_count": 0
}

Field	Meaning
`event_type`	`CREATE`, `UPDATE`, or `DELETE`.
`event_id`	A unique ID for the change. Use it to ignore duplicates.
`table_name`, `table_id`, `database_id`	Where the change happened.
`row_id`	The record that changed.
`field_name`, `old_value`, `new_value`	The field that changed and its values before and after, when the change concerns a single field.
`new_row`	The record as it is after the change.
`created_by`	Who made the change.
`delivery_id`, `subscription_id`	This delivery and the webhook it belongs to.
`resend_count`	How many times this delivery has been resent by hand.

Each request also carries these headers: X-Sapugo-Signature, X-Sapugo-Delivery-Id, X-Sapugo-Subscription-Id, X-Sapugo-Attempt, X-Sapugo-Event-Type, X-Sapugo-Event-Id, and X-Sapugo-Timestamp.

Check the signature#

Before trusting a request, check that it was signed with your secret. The X-Sapugo-Signature header has the form sha256= followed by a hex-encoded HMAC-SHA256 of the raw request body, using the signing secret as the key.

const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    expected.length === signatureHeader.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
  );
}

Compute the signature over the body exactly as it arrived, before parsing the JSON.

Delivery and retries#

Reply with any 2xx status to confirm a delivery. Reply quickly and do slow work afterwards, because a request that takes too long counts as failed.
Failed deliveries are retried automatically. Server errors, timeouts, and the statuses 408, 425, and 429 are retried. Other 4xx responses are not.
A delivery can arrive more than once. Use event_id to skip events you've already handled.
After 20 failures in a row, the webhook is switched off and shows Auto-disabled. Fix the receiver, then turn the webhook back on.

Delivery logs#

The Delivery logs tab lists every delivery with its status, event, number of attempts, and duration. Open one to see the request payload, the response, and a timeline of attempts.

Status	Meaning
Pending	Waiting to be sent.
Delivering	Being sent now.
Delivered	Your receiver confirmed it.
Retrying	An attempt failed and another is scheduled.
Failed	The delivery failed.
Dead lettered	All retries are used up.
Resent	The delivery was sent again by hand.

Click Resend on a delivery to send the original payload again, for example after fixing a bug in your receiver.

Manage webhooks#

Rotate creates a new signing secret. Receivers using the old secret start failing until you update them.
Archive stops a webhook for good. Its delivery history is kept.
Edit a webhook to change its tables, events, or address, or to switch Active off for a while.

Webhooks are included on selected plans, and you need permission to manage them. Webhooks aren't available on time series tables. Each payload can be up to 256 KB.

WorkflowsCall other systems with your own logic.Other systems stepsHTTP, FTP, EDI, and AI steps.