Webhook payload reference

Every Embers webhook is a JSON POST with the same envelope around an event-specific data object. This page lists every field, which ones to build on, and which ones are capped or conditional.

The envelope

account lets an agency route events from several client workspaces through one receiver. The 2026-09-10 schema dropped account.type, so route on account.id. Ignore keys you do not recognise.

Event types

Send lead events to your own endpoint covers when each one fires.

The lead object

data.lead is the same on every lead event.

Status values are active (shown as Pending in the app), contacted, replied, call_booked, not_interested, and dismissed. The leads list describes each one.

Two numbers the app shows are derived rather than sent. Engagement rate is engagement_count divided by follower_count. Grade comes from score: A at 80 or more, B at 60, C at 40, D at 20, F below that.

Join on linkedin_urn

Join people on lead.linkedin_urn. Do not key on linkedin_url: people change their vanity slug, and some are only ever seen in URN form, so one person can appear under two URLs. lead.id is stable per workspace and person, but when two member records are merged the losing id stops appearing. When linkedin_urn is blank on an older record, fall back to lead.id.

Contact fields

lead.contact appears only when the workspace is on a paid Solo plan or above. On Free, and during the free trial, the key is omitted entirely.

A webhook never triggers a fresh lookup and never invents an address. Reveal a lead’s email and phone explains how contacts get stored. Comment text can still contain details a person published, but that is public post content, not the contact object.

The engagement object

On lead.created, lead.status_changed, and test samples of them, data.engagement is the recent form:

• recent: the lead’s 10 most recent engagements, newest first.
• by_type: counts by engagement_type across those 10.
• first_engaged_at, last_engaged_at: the range they cover.

On lead.engagement.added it is the batched form, one event per lead per scan:

• engagement_count: how many engagements Embers first saw between window_start and window_end.
• engagements: the lead’s most recent engagements, newest first, up to 50. It can include some that an earlier event already carried.
• truncated: true when engagement_count is larger than the array.

Embers sends at most 500 lead.engagement.added events per workspace per scoring pass.

Status, report, and test fields

lead.status_changed adds previous_status, status, and changed_at beside lead. Blocking a company sends one with status set to dismissed.

report.generated carries data.report with id, title, status, date_range, date_start, date_end, share_url (the public link), and view_count, plus reason (created or regenerated) and generated_at. It leaves out the report snapshot. See client reports.

webhook.test carries is_test: true, sample_event_type, and a sample of that event with placeholder data. A sample includes contact when your plan would.

{
  "id": "e1b4f6e8-4c4a-4f50-b3c7-2ef2f97d5012",
  "type": "lead.status_changed",
  "api_version": "2026-07-20",
  "schema_version": "2026-09-10",
  "created_at": "2026-07-20T10:00:00+00:00",
  "account": {
    "id": "4d2f0eb9-81e5-4f20-8a60-25cbb9fe9ea5",
    "name": "Acme LinkedIn"
  },
  "data": {
    "lead": {
      "id": "967caf1c-c0a6-4b98-9f3b-1e0811fb53b4",
      "name": "Alex Smith",
      "headline": "VP Sales at Acme",
      "title": "VP Sales",
      "company": "Acme",
      "industry": "Insurance",
      "location": "Chicago",
      "linkedin_url": "https://www.linkedin.com/in/alex-smith/",
      "linkedin_urn": "ACoAAABBBCCCDDDEEEFFFGGG",
      "score": 82,
      "icp_match": true,
      "icp_confidence": 90,
      "icp_reason": "Insurance principal with clear sales authority.",
      "trend": "rising",
      "top_signals": ["Commented on multiple posts"],
      "sources": ["post_engagement"],
      "status": "contacted",
      "follower_count": 4200,
      "first_seen_at": "2026-06-02T09:15:00+00:00",
      "work_history": [
        {
          "company": "Acme",
          "title": "VP Sales",
          "start_date": "2021-04",
          "end_date": "",
          "location": "Chicago",
          "industry": "Insurance"
        }
      ],
      "certifications": [],
      "contact": {
        "email": "a***@acme.example",
        "phone": null,
        "enriched_at": "2026-07-01T00:00:00+00:00",
        "last_verified_at": "2026-07-01T00:00:00+00:00",
        "included": true,
        "source": "harvest",
        "confidence": "safe",
        "status": "ready"
      }
    },
    "engagement": {
      "recent": [
        {
          "engagement_type": "comment",
          "engagement_category": "comment",
          "engaged_at": "2026-07-19T14:02:00+00:00",
          "engaged_at_precision": "exact",
          "source": "post",
          "comment_text": "This matches what we see at renewal.",
          "post_url": "https://www.linkedin.com/feed/update/7481311828074078208/",
          "post_author_name": "Your Name",
          "post_author_type": "you",
          "post_snippet": "A post about renewal cycles in commercial insurance.",
          "competitor_name": "",
          "intent_category": "pain_alignment"
        }
      ],
      "by_type": { "comment": 1 },
      "first_engaged_at": "2026-07-19T14:02:00+00:00",
      "last_engaged_at": "2026-07-19T14:02:00+00:00"
    },
    "previous_status": "active",
    "status": "contacted",
    "changed_at": "2026-07-20T10:00:00+00:00"
  }
}

Related