Overview#
Webhooks allow your application to receive real-time notifications when events occur in AutomateNexus CRM. Instead of polling the API for changes, webhooks push data to your endpoint as events happen, reducing latency and API usage. Every delivery is signed, failed deliveries are retried, and each webhook keeps a delivery log you can inspect in the app. Webhooks are created and managed under Administration → Integrations → Developer → Webhooks; there is no REST endpoint for managing them. This guide covers creating a webhook, event types, the payload format, signature verification, retries, and troubleshooting.
Create a Webhook#
- Go to Administration → Integrations → Developer and scroll to Webhooks.
- In the Create webhook card, fill in:
- Name (required) — A label for the webhook, for example "Zapier — new leads".
- Endpoint URL (required) — The URL that will receive the POST requests. It must be a full
https://address on the public internet: a plainhttp://address, or one that is private or local (such aslocalhostor an internal network address), is refused when you save, with a message that says why. - Events (required) — Tick at least one event. Events are grouped by Contacts, Deals, Customers, Companies, Tasks, Tickets, and Forms.
- Description — Optional.
- Click Create webhook. The Webhook signing secret dialog shows the secret (it starts with
whsec_). Copy it now: it is stored encrypted and cannot be shown again, only rotated.
An organization can have up to 50 webhooks.
Manage Webhooks#
The Active webhooks list shows each webhook's name, an Active or Inactive badge, a badge counting consecutive failures if there are any, the URL, the subscribed events, and the time of the last successful and last failed delivery. Each row offers:
- Test — Sends a real, signed test delivery (see Test a Webhook).
- Deliveries — Opens the delivery log (see Delivery Log).
- The key icon — Rotate signing secret. The new secret is shown once; the old one stops working immediately.
- The on/off switch — Enables or disables the webhook. While a webhook is off, its events are not queued.
- The trash icon — Deletes the webhook and its delivery log.
Available Event Types#
Contact Events#
- contact.created — A contact is created.
- contact.updated — A contact is updated.
Deal Events#
- deal.created — A deal is created.
- deal.updated — A deal is updated.
- deal.stage_changed — A deal moves to a different stage. A stage change also counts as an update, so a webhook subscribed to both events receives both.
Customer Events#
- customer.created — A customer is created.
- customer.updated — A customer is updated.
Company Events#
- company.created — A company is created.
- company.updated — A company is updated.
Task Events#
- task.created — A task is created.
- task.updated — A task is updated.
Task events fire for project tasks — the ones under Projects → Tasks and in the REST API's /api/tasks resource, with object set to project_tasks — and for the CRM to-dos that AI agents and meeting action items create (object set to tasks).
Ticket Events#
- ticket.created — A support ticket is filed.
- ticket.updated — A ticket or its team-only details change.
- ticket.status_changed — A ticket's status or internal status changes.
- ticket.tags_changed — A ticket's internal tags change.
- ticket.comment_created — A reply, a client message, or an internal note is added.
A change to a ticket's status sends both ticket.updated and ticket.status_changed; a change to its internal tags sends both ticket.updated and ticket.tags_changed.
Form Events#
- form.submitted — A form receives a submission.
The .updated events fire on any change to the record. There are no delete events. Test deliveries use the event name webhook.test.
Records the CRM writes in bulk on your behalf are quiet: what an import or a move from another CRM brings in, a merge of duplicates, and a restore from Recently deleted send no webhooks. Records created or changed through the REST API do send them.
Webhook Payload Format#
Every delivery is a POST request with a JSON body. data holds the full record as it is after the event; previous holds the record as it was before, for .updated and deal.stage_changed events, and is null otherwise. object names the kind of record: contacts, deals, customers, companies, project_tasks or tasks, form_submissions, or support_ticket.
{
"event": "deal.stage_changed",
"occurred_at": "2026-03-21T10:30:00.418512+00:00",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"object": "deals",
"data": {
"id": "6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c",
"title": "Enterprise License - Acme Corp",
"value": 75000,
"currency": "USD",
"stage": "negotiation",
"probability": 60,
"customer_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"updated_at": "2026-03-21T10:30:00.418512+00:00"
},
"previous": {
"id": "6d2f8b4a-1c3e-4f5a-9b7c-8d9e0f1a2b3c",
"title": "Enterprise License - Acme Corp",
"value": 75000,
"currency": "USD",
"stage": "proposal",
"probability": 50,
"customer_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"updated_at": "2026-03-18T15:30:00.000000+00:00"
}
}Ticket Payloads#
A ticket event carries the ticket under data, with its team-only details (internal status, tags, fields, notes, and linked task address) under data.internal. It has no previous: ticket.updated, ticket.status_changed, and ticket.tags_changed say what changed under changes, each field with its from and to, and ticket.comment_created carries the new message under comment (its content, whether it is internal, whether it came from the client or the team, and its attachments). The client never sees internal; a webhook is your organization's own.
{
"event": "ticket.status_changed",
"occurred_at": "2026-10-17T09:12:00.418512+00:00",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"object": "support_ticket",
"data": {
"id": "8f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"ticket_number": "TKT-1042",
"subject": "Homepage banner",
"status": "in_progress",
"priority": "medium",
"customer_id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"assigned_to": "b7e3c1d2-5f6a-4b8c-9d0e-1f2a3b4c5d6e",
"internal": {
"status": "Waiting on dev",
"tags": ["retainer", "design"],
"fields": { "effort": "M" },
"notes": "Source files requested",
"external_task_url": "https://app.clickup.com/t/86abc"
}
},
"changes": {
"internal.status": { "from": "Triage", "to": "Waiting on dev" }
}
}Every delivery carries these headers:
- X-Webhook-Id — The delivery's ID. It stays the same across retries of the same delivery, so use it to deduplicate.
- X-Webhook-Event — The event name.
- X-Webhook-Timestamp — Unix time in seconds when the delivery was signed.
- X-Webhook-Signature — The signature, described below.
- User-Agent —
AutomateNexusCRM-Webhooks/1.0.
Signature Verification#
Every delivery includes an X-Webhook-Signature header of the form t=<timestamp>,v1=<signature>. The signature is the hex-encoded HMAC-SHA256, keyed with your webhook's signing secret, of the timestamp, a period, and the raw request body. Always verify it to ensure the payload is authentic and has not been tampered with.
X-Webhook-Signature: t=1731430000,v1=8f2a1c...How to Verify#
- Split the header on commas and read
tandv1. - Take the raw request body exactly as received (before any JSON parsing).
- Compute HMAC-SHA256 over the string
<t>.<raw body>using your signing secret, hex-encoded. - Compare the result with
v1using a constant-time comparison.
Node.js Example#
const crypto = require('crypto');
function verifyWebhook(rawBody, signatureHeader, secret) {
// signatureHeader looks like "t=1731430000,v1=8f2a1c..."
const parts = Object.fromEntries(
signatureHeader.split(',').map((kv) => kv.split('='))
);
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected, 'hex'),
Buffer.from(parts.v1, 'hex')
);
}Python Example#
import hmac
import hashlib
def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
parts = dict(kv.split("=", 1) for kv in signature_header.split(","))
message = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])Retry Logic#
A delivery counts as failed when your endpoint returns a non-2xx status code or does not respond within 10 seconds. A redirect (a 3xx answer) is not followed and counts as a failed attempt too: point the webhook at the address the redirect leads to. AutomateNexus CRM makes up to four attempts per delivery — the first attempt and three retries — with growing delays:
- Retry 1: After 1 minute
- Retry 2: After 5 minutes
- Retry 3: After 30 minutes
Retries are picked up by a background job that runs every five minutes, so a retry can arrive a few minutes after its scheduled time. The first attempt is made right after the event; if that send is lost, the same job picks the delivery up within a few minutes.
The address is checked again before every attempt. If it is not a public https:// address (for example, a name that now points to a private network), nothing is sent, and the delivery fails at once with no retries; the delivery log says why.
After the last failed attempt the delivery is marked failed and the webhook's consecutive-failure count goes up; it is shown as a badge in the list and reset by the next successful delivery. AutomateNexus CRM does not turn a webhook off on its own; use the switch in the list if you need to pause it.
Delivery Log#
Click Deliveries on a webhook to open its delivery log. It shows the latest 50 deliveries; rows older than 30 days are removed automatically. Each row shows the event, its status (Pending, Delivered, or Failed), the HTTP status code and response time of the last attempt, the number of attempts made out of the maximum, and when it was created. Expand a row to see the last error, the time of the next retry for a pending delivery, every attempt with its status code, response time, error, and the first 500 characters of your endpoint's response, and the exact payload that was sent.
Test a Webhook#
Click Test on a webhook to send a real, signed delivery of the webhook.test event to its URL. A test is a single attempt with no retries, and it appears in the delivery log like any other delivery. The app reports the HTTP status and response time your endpoint returned.
{
"event": "webhook.test",
"occurred_at": "2026-03-21T10:30:00.000Z",
"organization_id": "550e8400-e29b-41d4-a716-446655440000",
"object": "webhook_subscriptions",
"data": {
"subscription_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
"message": "Test delivery from AutomateNexus CRM. If you can verify the signature, you are set up correctly.",
"test": true
},
"previous": null
}Best Practices#
- Respond quickly: Return a 2xx status code well within the 10-second limit. Process the webhook payload asynchronously (e.g., add to a queue) rather than performing long operations in the request handler.
- Handle duplicates: Use the
X-Webhook-Idheader to deduplicate. A retried delivery carries the same ID, and the same event may occasionally be delivered more than once. - Use a public HTTPS address: Webhooks are sent only to public
https://addresses, which protects payload data in transit. - Monitor the delivery log: Check Deliveries and the consecutive-failure badge regularly to catch failures early.
- Rotate secrets: Rotate the signing secret if it may have leaked. The old secret stops working immediately, so update your verification code at the same time.
Troubleshooting#
- Not receiving webhooks: Check that the webhook is Active, that the event you expect is among its subscribed events, and that the endpoint URL is publicly reachable and accepts POST requests. Open Deliveries: if deliveries are listed as failed, the error column tells you why; if nothing is listed, the event has not fired.
- Signature verification failing: Compute the HMAC over
<t>.<raw body>, not over the body alone, and use the raw request body rather than re-serialized JSON. Make sure you are using the current secret — rotating it invalidates the previous one. - "Endpoint answered with a redirect": Redirects are not followed. Update the webhook's URL to the final address, often the same address with
https://or a trailing slash. - The address is refused when you save, or deliveries fail with "Not sent": A webhook goes only to a public
https://address. Use your endpoint's public address, notlocalhostor an internal one; for local development, expose it through a tunnel with a public https address. - Events missing after an import: Imports, moves from another CRM, merges, and restores do not send webhooks. Read the records through the REST API instead.
- Consecutive failures keep growing: Fix the endpoint, then click Test; a successful delivery resets the count.
- Older deliveries missing from the log: The log keeps the latest 50 deliveries and removes rows older than 30 days.