Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let Novala send a notification to your server whenever something happens in your account — a new inspection is completed, an invoice is paid, or a work order is created. Instead of polling the Novala API for changes, your system receives an HTTP POST request with event details immediately when the event fires.

​
Add a webhook endpoint

Navigate to Settings → Webhooks, then click Add Endpoint.
1

Enter your endpoint URL

Provide the HTTPS URL where Novala should send events. The URL must be publicly accessible. During development, a tunneling tool like ngrok can expose a local server.
2

Add a description (optional)

Add a short label to help you identify this endpoint later (for example, “Acumatica sync” or “Slack alerts”).
3

Choose which events to receive

By default, Subscribe to all events is checked, which means your endpoint receives every event type Novala emits. Uncheck this to select specific event types from the list.
4

Click Create

Novala registers the endpoint and begins delivering matching events immediately.

​
Event types

Events are grouped by module. The event type is included in every payload as the type field.
Event typeWhen it fires
contacts.company.createdA new company is added
contacts.contact.createdA new contact is added
Event typeWhen it fires
calso.inspection.completedAn inspection is marked complete
calso.report.generatedAn inspection report is generated
calso.finding.createdA new finding is recorded on an inspection
Event typeWhen it fires
invoicing.invoice.paidAn invoice is marked as paid
invoicing.invoice.overdueAn invoice passes its due date unpaid
Event typeWhen it fires
leads.lead.createdA new lead is added
leads.lead.convertedA lead is converted to a deal or contact
Event typeWhen it fires
work-order.createdA new work order is created
work-order.completedA work order is marked complete
Event typeWhen it fires
bookings.confirmedA booking is confirmed
bookings.cancelledA booking is cancelled
Event typeWhen it fires
workflows.execution.completedA workflow finishes successfully
workflows.execution.failedA workflow encounters an error

​
Payload format

Every Novala webhook delivery is an HTTPS POST with a Content-Type: application/json body. The top-level structure is the same for all event types: 
{
  "id": "evt_01j9z2k3m4n5p6q7r8s9t0u1v2",
  "type": "calso.inspection.completed",
  "tenantId": "ten_01j9z2k3m4n5p6q7r8s9",
  "timestamp": "2026-05-02T14:23:45.123Z",
  "source": "calso",
  "data": {
    "inspectionId": "ins_01j9z2k3m4n5p6q7",
    "equipmentId": "eqp_01j8x1k2m3n4p5q6",
    "status": "completed",
    "completedAt": "2026-05-02T14:23:44.000Z",
    "technicianId": "usr_01j7w0j1l2m3o4p5",
    "findingCount": 3,
    "reportUrl": "https://app.novala.ai/inspections/ins_01j9z2k3m4n5p6q7/report"
  }
}
FieldDescription
idUnique ID for this event
typeThe event type string
tenantIdYour Novala organization ID
timestampISO 8601 timestamp when the event fired
sourceThe module that emitted the event
dataEvent-specific payload — contents vary by event type

​
Verify webhook signatures

Every delivery includes three headers you can use to verify that the request came from Novala and has not been tampered with:
HeaderDescription
X-Novala-SignatureHMAC-SHA256 signature of the payload
X-Novala-TimestampISO 8601 timestamp of the delivery attempt
X-Novala-Delivery-IdUnique ID for this delivery attempt
The signature is computed as sha256=HMAC-SHA256(timestamp + "." + raw_body, endpoint_secret). To verify a delivery: 
const crypto = require("crypto");

function verifySignature(rawBody, timestamp, signature, secret) {
  const message = `${timestamp}.${rawBody}`;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(message)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Always verify the signature before processing a webhook payload. Reject any request where the signature does not match.

​
Retry behavior

If your endpoint returns a non-2xx response or does not respond within 10 seconds, Novala retries the delivery automatically with exponential backoff:
AttemptDelay after failure
1st retry1 minute
2nd retry5 minutes
3rd retry25 minutes
4th retry2 hours
5th retry10 hours
After 5 failed attempts, the delivery is marked as permanently failed. If an endpoint accumulates 10 consecutive failures, Novala automatically disables it to protect your system from continued errors.
Return an HTTP 200 response as quickly as possible — before you process the event. Use a queue or background worker to handle the business logic so slow processing doesn’t cause timeouts.

​
Monitor deliveries

Click the eye icon next to any endpoint to open its delivery log. Each entry shows the event type, status, HTTP response code, attempt number, timestamp, and any error message. From the delivery log, you can click Replay on any delivery to resend it to the endpoint immediately, regardless of its current status. Replaying follows the same signature and retry logic as original deliveries.

​
Test an endpoint

Click the test tube icon next to any endpoint to send a test event. Novala delivers a sample payload and shows you the HTTP response code. Use this to confirm your endpoint is reachable and processing signatures correctly before you go live.

​
Endpoint status

StatusMeaning
ActiveReceiving events normally
FailingRecent deliveries have failed; Novala is retrying
Auto-disabledDisabled after 10 consecutive failures; re-enable from the endpoint list after fixing your receiver
InactiveManually disabled