SpartivoDocs
Open app
Get started
OverviewQuickstartAuthenticationRequests and errors
API reference
RecordsModules and fieldsFilesMessagingDocuments and e-signatureFunctionsWebhooks
Spartivo Script
IntroductionLanguage guideCRM and actionsBuilt-in functionsExamples
API reference

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

EventSent when
record.createdA record is created, by a person, an import, a form, a rule or the API.
record.updatedA record changes. The payload includes the values before the change.
record.deletedA record is moved to the recycle bin.
record.approved, record.rejectedAn approval process finishes.
message.receivedA customer sends a message on any connected channel.
message.sentA message goes out to a customer.
conversation.opened, conversation.closedA conversation starts or is closed.
envelope.sentA document is sent for signature.
envelope.completedEveryone has signed. The payload includes the id of the signed PDF.
envelope.declinedA recipient declines to sign.

Choose * to receive every event.

What your server receives

A POST with a JSON body and these headers:

HeaderValue
x-spartivo-eventThe event name.
x-spartivo-deliveryA unique id for this event. It stays the same across retries and is also in the body as id.
x-spartivo-attempt1 for the first try, up to 6.
x-spartivo-signaturePresent when the webhook has a secret. See below.
record.updated
{
  "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"
  }
}
envelope.completed
{
  "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.

AttemptSent
1Straight away
21 minute later
35 minutes later
430 minutes later
52 hours later
68 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 2xx status quickly and do slow work afterwards.
  • Because of retries the same event can arrive more than once. Remember the x-spartivo-delivery ids you have handled and skip repeats.
  • Events can arrive out of order. Use updatedAt on the record to decide which is newest.
Previous← FunctionsNextSpartivo Script →
On this page
Set one upEventsWhat your server receivesCheck the signatureRetriesGood practice