Webhook Integration

01 · Introduction

Overview

Subscribe to contact events and ConnectMachine sends a JSON POST to your HTTPS endpoint whenever one fires. Deliveries are asynchronous and retried on transient failures.

02 · Catalog

Supported Events

Three event types cover the full contact lifecycle.

03 · Setup

Create a Webhook

1. Open webhook settings in ConnectMachine.
2. Add your HTTPS endpoint as the destination URL.
3. Choose events to subscribe to.
4. Save, then send a test event below.
5. Check delivery logs for status and timings.

04 · Try it

Send a Test Event

Fire a sample contacts.* delivery to verify your endpoint accepts the payload and returns 2xx.

05 · Delivery

Delivery

Every delivery is a JSON POST with the headers below. Transient failures are retried; logs show the result.

• Timeout: 10 seconds.
• Retries: up to 3, 6 minutes apart (4 attempts total).
• Logs: include status, status_code, timings, and a response body capped at 4096 bytes.

06 · Payload

Payload

Created and updated events share an envelope wrapping one or more contact objects. Deleted events carry IDs only.

Envelope

{
  "event_id": "delivery_id",
  "occurred_at": "2026-05-15T10:30:00Z",
  "source": "contact_import",
  "source_id": "import_id",
  "batch": {
    "index": 1,
    "count": 100,
    "max_size": 100
  },
  "data": {
    "event_type": "contacts.created",
    "contacts": []
  }
}

Contact body

A complete sample contacts.created delivery, with the contact field reference alongside.

{
  "event_id": "delivery_id",
  "occurred_at": "2026-05-15T10:30:00Z",
  "source": "contact_import",
  "source_id": "import_id",
  "batch": {
    "index": 1,
    "count": 100,
    "max_size": 100
  },
  "data": {
    "event_type": "contacts.created",
    "contacts": [
      {
        "id": "contact_id",
        "first_name": "John",
        "last_name": "Doe",
        "company": "Example Corp",
        "job_title": "Product Manager",
        "label": "Work",
        "notes": "Met at event",
        "primary_email": "john.doe@example.com",
        "primary_phone": "+15550101010",
        "emails": [{ "label": "Work", "value": "john.doe@example.com" }],
        "phones": [{ "label": "Mobile", "value": "+15550101010" }],
        "websites": [{ "label": "Company", "value": "https://example.com" }],
        "socials": [
          { "linkedin_url": "https://linkedin.com/in/john-doe" },
          { "github_url": "https://github.com/john-doe" }
        ],
        "custom": [{ "label": "CRM Owner", "value": "Sales" }],
        "address": {
          "formatted": "123 Market Street, San Francisco, CA, USA, 94105",
          "raw": {}
        },
        "where_we_met": {
          "formatted": "Moscone Center, San Francisco, CA, USA",
          "raw": {}
        },
        "tags": [{ "name": "Conference", "type": "event" }],
        "notetaker_sessions": [
          {
            "session_id": "session_id",
            "title": "Meeting note",
            "summary_url": "https://...",
            "audio_url": "https://...",
            "created_at": "2026-05-15T10:00:00Z",
            "updated_at": "2026-05-15T10:05:00Z"
          }
        ],
        "created_at": "2026-05-15T10:00:00Z",
        "updated_at": "2026-05-15T10:05:00Z"
      }
    ]
  }
}

Deleted events

Same envelope, but contacts is replaced by contact_ids.

{
  "event_id": "delivery_id",
  "occurred_at": "2026-05-15T10:30:00Z",
  "source": "manual",
  "source_id": "source_id",
  "data": {
    "event_type": "contacts.deleted",
    "contact_ids": ["contact_id"]
  }
}

07 · Tips

Best Practices & Troubleshooting

Best Practices

• Return 2xx quickly — acknowledge first, queue slow work for the background.
• Be idempotent — events can be redelivered; key off X-ConnectMachine-Delivery-ID.
• Tolerate missing optional fields — not every contact has every field.
• Log event_type and delivery_id for traceability.
• Keep responses small — bodies are truncated to 4096 bytes in logs.

Troubleshooting