Powered by eniston
  1. Overview
  2. API Reference
  3. Webhooks API

Webhooks API

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. This guide covers creating webhook subscriptions, event types, payload formats, signature verification, and troubleshooting.

Create a Webhook Subscription

POST /v1/webhooks

Request Body

  • url (string, required) — The HTTPS endpoint URL that will receive webhook payloads. Must be publicly accessible.
  • events (array, required) — Array of event types to subscribe to.
  • secret (string) — A secret key used for HMAC-SHA256 signature verification. Auto-generated if not provided.
  • description (string) — A description for this webhook subscription.
  • active (boolean) — Whether the webhook is active. Default: true.

Example

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/automatenexus",
    "events": ["contact.created", "deal.stage_changed", "deal.won"],
    "secret": "whsec_your_secret_key_here",
    "description": "Main integration webhook"
  }'

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-app.com/webhooks/automatenexus",
    "events": ["contact.created", "deal.stage_changed", "deal.won"],
    "secret": "whsec_your_secret_key_here",
    "active": true,
    "created_at": "2026-03-21T10:00:00Z"
  }
}

List Webhooks

GET /v1/webhooks

Returns all webhook subscriptions in your workspace.

Get a Webhook

GET /v1/webhooks/:id

Update a Webhook

PUT /v1/webhooks/:id

Update the URL, events, or active status of a webhook subscription.

Delete a Webhook

DELETE /v1/webhooks/:id

Available Event Types

Contact Events

  • contact.created — A new contact was created.
  • contact.updated — A contact's information was modified.
  • contact.deleted — A contact was permanently deleted.
  • contact.merged — Two contacts were merged.
  • contact.tag_added — A tag was added to a contact.
  • contact.status_changed — A contact's status changed (e.g., lead to customer).

Deal Events

  • deal.created — A new deal was created.
  • deal.updated — A deal's information was modified.
  • deal.stage_changed — A deal moved to a different pipeline stage.
  • deal.won — A deal was marked as won.
  • deal.lost — A deal was marked as lost.
  • deal.deleted — A deal was deleted.

Task Events

  • task.created — A new task was created.
  • task.completed — A task was marked as completed.
  • task.assigned — A task was assigned or reassigned.
  • task.overdue — A task has passed its due date without completion.

Activity Events

  • activity.logged — An activity (call, email, meeting, note) was logged.

Invoice Events

  • invoice.created — A new invoice was created.
  • invoice.paid — An invoice was marked as paid.
  • invoice.overdue — An invoice has passed its due date.

Form Events

  • form.submitted — A form was submitted by a visitor.

Webhook Payload Format

Every webhook delivery sends a POST request to your endpoint with a JSON payload:

{
  "id": "evt_abc123def456",
  "event": "deal.stage_changed",
  "timestamp": "2026-03-21T10:30:00Z",
  "workspace_id": "ws_xyz789",
  "data": {
    "deal": {
      "id": "deal_xyz789",
      "title": "Enterprise License - Acme Corp",
      "value": 75000,
      "currency": "USD",
      "pipeline_id": "pipe_001",
      "stage_id": "stage_004",
      "stage_name": "Negotiation",
      "previous_stage_id": "stage_003",
      "previous_stage_name": "Proposal",
      "owner_id": "usr_abc123"
    },
    "changed_by": {
      "id": "usr_abc123",
      "name": "Sarah Johnson"
    }
  }
}

Signature Verification

Every webhook delivery includes an X-AutomateNexus-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the payload is authentic and has not been tampered with.

How to Verify

  1. Get the raw request body (before any JSON parsing).
  2. Compute HMAC-SHA256 using your webhook secret and the raw body.
  3. Compare the computed signature with the X-AutomateNexus-Signature header value.

Node.js Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

Python Example

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    computed = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature)

Warning: Always use constant-time comparison (like timingSafeEqual or compare_digest) to prevent timing attacks.

Retry Logic

If your endpoint returns a non-2xx status code or times out (30-second limit), AutomateNexus CRM will retry the delivery using exponential backoff:

  • Retry 1: After 5 seconds
  • Retry 2: After 30 seconds
  • Retry 3: After 2 minutes
  • Retry 4: After 15 minutes
  • Retry 5: After 1 hour

After 5 failed retries, the delivery is marked as failed. If a webhook consistently fails (more than 10 consecutive failures), it will be automatically deactivated. You will receive an email notification when this happens.

Delivery Logs

GET /v1/webhooks/:id/logs

Returns the delivery history for a webhook, including request/response details, timestamps, and status codes. Useful for debugging failed deliveries.

{
  "success": true,
  "data": [
    {
      "id": "del_001",
      "event": "deal.won",
      "status": "delivered",
      "response_code": 200,
      "response_time_ms": 145,
      "attempts": 1,
      "delivered_at": "2026-03-21T10:30:01Z"
    },
    {
      "id": "del_002",
      "event": "contact.created",
      "status": "failed",
      "response_code": 500,
      "response_time_ms": 2100,
      "attempts": 5,
      "last_attempt_at": "2026-03-21T11:30:00Z",
      "error": "Server returned 500 Internal Server Error"
    }
  ]
}

Test a Webhook

POST /v1/webhooks/:id/test

Sends a test payload to your webhook endpoint. The test payload contains sample data for each event type you have subscribed to.

curl -X POST "https://app.automatenexuscrm.com/functions/v1/api/webhooks/wh_abc123/test" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

  • Respond quickly: Return a 200 status code within 5 seconds. Process the webhook payload asynchronously (e.g., add to a queue) rather than performing long operations in the request handler.
  • Handle duplicates: Use the id field in the payload to deduplicate events. The same event may be delivered more than once in rare cases.
  • Use HTTPS: Webhook URLs must use HTTPS to protect payload data in transit.
  • Monitor delivery logs: Regularly check your webhook delivery logs to catch failures early.
  • Rotate secrets: Periodically rotate your webhook secret for security. Update both the webhook subscription and your verification code simultaneously.

Troubleshooting

  • Not receiving webhooks: Verify your endpoint URL is publicly accessible and accepts POST requests. Check firewall rules and SSL certificate validity.
  • Signature verification failing: Ensure you are using the raw request body (not parsed JSON) for HMAC computation. Check that you are using the correct webhook secret.
  • Webhook deactivated automatically: This happens after 10+ consecutive failures. Fix the underlying issue, then reactivate via PUT /v1/webhooks/:id with {"active": true}.
  • Delayed deliveries: Webhooks are delivered in near-real-time but may experience delays of up to 60 seconds during high-traffic periods.
Last updated March 21, 2026
Was this article helpful?