Webhooks
A webhook calls your server when something happens in Spartivo, so you do not have to keep asking.
Set one up
Open Setup → Developer space → Webhooks and add the address of your endpoint, the events you want and, optionally, a module to limit record events to. Add a secret so you can check that calls really come from Spartivo.
Events
| Event | Sent when |
|---|---|
record.created | A record is created, by a person, an import, a form, a rule or the API. |
record.updated | A record changes. The payload includes the values before the change. |
record.deleted | A record is moved to the recycle bin. |
record.approved, record.rejected | An approval process finishes. |
message.received | A customer sends a message on any connected channel. |
message.sent | A message goes out to a customer. |
conversation.opened, conversation.closed | A conversation starts or is closed. |
envelope.sent | A document is sent for signature. |
envelope.completed | Everyone has signed. The payload includes the id of the signed PDF. |
envelope.declined | A recipient declines to sign. |
Choose * to receive every event.
What your server receives
A POST with a JSON body and these headers:
| Header | Value |
|---|---|
x-spartivo-event | The event name. |
x-spartivo-delivery | A unique id for this event. It stays the same across retries and is also in the body as id. |
x-spartivo-attempt | 1 for the first try, up to 6. |
x-spartivo-signature | Present when the webhook has a secret. See below. |
{
"id": "cfe48270-5322-4396-b772-5c2203fd1755",
"event": "record.updated",
"at": "2026-11-18T08:33:19.300Z",
"data": {
"tenantId": "4e4552cc-2ac8-4cda-8777-9eed5e4e5b64",
"module": "leads",
"record": {
"id": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
"ownerId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22",
"name": "Aisha Khan",
"data": {
"email": "aisha@example.com",
"company": "Northwind Trading",
"source": "whatsapp",
"status": "contacted"
},
"tags": [
"api"
],
"score": 0,
"createdAt": "2026-11-18T08:33:18.996Z",
"updatedAt": "2026-11-18T08:33:18.996Z",
"deletedAt": null
},
"before": {
"email": "aisha@example.com",
"company": "Northwind Trading",
"source": "whatsapp",
"status": "new"
},
"changes": {
"status": {
"from": "new",
"to": "contacted"
}
},
"actorId": "035607f1-9fd1-44bc-ac7f-d5128d5afc22"
}
}{
"id": "ac21e80f-5bfc-49cd-8eef-cc55a3bfef2b",
"event": "envelope.completed",
"at": "2026-11-17T08:52:11.000Z",
"data": {
"tenantId": "4e4552cc-2ac8-4cda-8777-9eed5e4e5b64",
"envelopeId": "8a1fc245-12cf-4617-ac1e-0bc0a23b9d92",
"recordId": "a0d3bf2c-688d-42da-83e1-d5e57d3e990d",
"fileId": "1c82ca55-bc02-4873-9d3b-f07e1691877e"
}
}Check the signature
When the webhook has a secret, each call carries an x-spartivo-signature header: the SHA-256 hash, in hex, of your secret followed by the exact body text. Work out the same hash on your side and compare before trusting the call.
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.SPARTIVO_WEBHOOK_SECRET;
app.post("/spartivo", express.raw({ type: "application/json" }), (req, res) => {
const body = req.body.toString("utf8");
const expected = crypto.createHash("sha256").update(SECRET + body).digest("hex");
const given = req.get("x-spartivo-signature") ?? "";
if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
return res.status(401).end();
}
const { event, data } = JSON.parse(body);
if (event === "record.created") {
console.log("New", data.module, data.record.name);
}
res.status(200).end();
});Retries
A delivery succeeds when your server answers with a 2xx status within 10 seconds. Anything else is tried again, with a longer wait each time.
| Attempt | Sent |
|---|---|
| 1 | Straight away |
| 2 | 1 minute later |
| 3 | 5 minutes later |
| 4 | 30 minutes later |
| 5 | 2 hours later |
| 6 | 8 hours later |
After the sixth attempt the delivery is marked as given up. Setup → Developer space → Webhooks lists every delivery that needed a retry, with your server's last answer and a Retry now button.
Good practice
- Answer with a
2xxstatus quickly and do slow work afterwards. - Because of retries the same event can arrive more than once. Remember the
x-spartivo-deliveryids you have handled and skip repeats. - Events can arrive out of order. Use
updatedAton the record to decide which is newest.