curl --request POST \
  --url https://app.octavehq.com/api/v2/analytics/webhook/receive/generic/{eventType} \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "eventTimestamp": "2024-02-03T10:30:00Z",
  "eventType": "sent",
  "subject": "Follow up on our conversation",
  "body": {
    "text": "Hi John, Just wanted to follow up on our call yesterday...",
    "html": "<p>Hi John,</p><p>Just wanted to follow up on our call yesterday...</p>"
  },
  "from": {
    "email": "sarah@company.com",
    "name": "Sarah Johnson"
  },
  "to": [
    {
      "email": "john@prospect.com",
      "name": "John Smith"
    }
  ],
  "conversationId": "conv_abc123",
  "campaignId": "campaign_xyz"
}
'

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "received": true,
  "connection": {
    "shouldProcess": true
  },
  "additionalData": {},
  "validationErrors": {
    "fieldErrors": {},
    "formErrors": [
      "<string>"
    ]
  }
}

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "message": "<string>"
}

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "message": "<string>"
}

Events

Log Event

Log a custom event — emails, calls, CRM, and social data from your own integrations (n8n, Clay, Make, etc.) — into the analytics pipeline.

Event Types

The {eventType} path parameter determines the expected payload schema. Each event type has its own set of supported sub-types:

`emails` — Email Events

Supported eventType values: sent, reply, opened, clicked, bounced, unsubscribed

Only sent and reply are processed for analytics; others are ingested but not processed.
Required fields: eventTimestamp, eventType, subject, body (text or html), from, to
Optional: cc, bcc, eventId, conversationId, campaignId, customMetadata

`calls` — Call/Meeting Events

Supported eventType values: transcript, scheduled, completed, missed

Only transcript is processed for analytics; others are ingested but not processed.
Required fields: eventTimestamp, eventType, title, transcript, participants
Optional: duration, recordingUrl, meetingPlatform, eventId, conversationId, customMetadata
Transcript formats: Can be a flat string (LLM will diarize into speaker turns) or a structured array of entries with speaker attribution (recommended — faster and more reliable).

`crm` — CRM Events

Supported eventType values: opportunity_created, deal_won, deal_lost, meeting_booked

All CRM event types are processed for analytics.
Required fields: eventTimestamp, eventType, opportunityId, opportunityName
Optional: amount, stage, accountName, contactEmail, contactName, closeDate, customMetadata

`social` — Social/LinkedIn Events

Supported eventType values: connection_sent, connection_accepted, message_sent, message_received

All social event types are processed for analytics.
Required fields: eventTimestamp, eventType, body (text or html), from, to
Optional: subject, eventId, conversationId, campaignId, messageType, campaignName, customMetadata

Deduplication

You can provide an optional eventId field for explicit deduplication. If not provided, an ID is auto-generated from the event content:

Emails: from_email + subject + timestamp + first_to_email
Calls: title + timestamp + first_participant + first_100_chars_transcript
CRM: opportunityId + eventType
Social: auto-generated from content

Authentication

Workspace is identified by API key, passed as a query parameter (api_key) or in the request header.

POST

api

analytics

webhook

receive

generic

{eventType}

curl --request POST \
  --url https://app.octavehq.com/api/v2/analytics/webhook/receive/generic/{eventType} \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "eventTimestamp": "2024-02-03T10:30:00Z",
  "eventType": "sent",
  "subject": "Follow up on our conversation",
  "body": {
    "text": "Hi John, Just wanted to follow up on our call yesterday...",
    "html": "<p>Hi John,</p><p>Just wanted to follow up on our call yesterday...</p>"
  },
  "from": {
    "email": "sarah@company.com",
    "name": "Sarah Johnson"
  },
  "to": [
    {
      "email": "john@prospect.com",
      "name": "John Smith"
    }
  ],
  "conversationId": "conv_abc123",
  "campaignId": "campaign_xyz"
}
'

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "received": true,
  "connection": {
    "shouldProcess": true
  },
  "additionalData": {},
  "validationErrors": {
    "fieldErrors": {},
    "formErrors": [
      "<string>"
    ]
  }
}

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "message": "<string>"
}

{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "message": "<string>"
}

Authorizations

api_key

string

header

required

Path Parameters

eventType

enum<string>

required

Type of event being sent

Available options:

emails,

calls,

crm,

social

Example:

"emails"

Query Parameters

api_key

string

Provide api key if not in header

Body

application/json

Webhook payload. The schema depends on the {eventType} path parameter:

emails — Email Event schema
calls — Call Event schema
crm — CRM Event schema
social — Social Event schema (LinkedIn/social outreach)

eventTimestamp

required

Timestamp of the event. Accepts an ISO 8601 string (e.g., "2024-02-03T10:30:00Z"), a Unix epoch in milliseconds (>= 1e12), or a Unix epoch in seconds. Must resolve to a date within 50 years past or 5 years future.

Example:

"2024-02-03T10:30:00Z"

eventType

enum<string>

required

Type of email event. Only 'sent' and 'reply' are processed for analytics; others are ingested but not processed.

Available options:

sent,

reply,

opened,

clicked,

bounced,

unsubscribed

subject

string

required

Email subject line

Example:

"Follow up on our conversation"

body

object

required

Email body. At least one of text or html must be provided.

Show child attributes

from

object

required

Sender

Show child attributes

object[]

required

Recipients (at least one required)

Minimum array length: 1

Show child attributes

object[]

CC recipients

Show child attributes

bcc

object[]

BCC recipients

Show child attributes

eventId

string

Explicit event ID for deduplication. If not provided, auto-generated from: from_email + subject + timestamp + first_to_email

Example:

"deal-001-email-sent-1"

conversationId

string

Conversation/thread ID for grouping related emails

campaignId

string

Campaign ID for grouping campaign emails

octaveRequestId

string

Octave request ID for tracking

sourceProviderName

string

Display override for the activity feed. Case-insensitive match against a supported provider name; when set, that provider's logo is shown instead of the generic Octave icon.

crmOpportunityId

string

Your system's deal ID. Links this event straight to that opportunity instead of Octave inferring the deal from participants and timing — which misses when the participant is not on the deal, and mis-fires when two deals share a domain.

Example:

"opp_12345"

crmAccountId

string

Your system's account/company ID, for account-level linking

Example:

"acct_67890"

crmAccountDomain

string

Account domain, used when no deal ID is known

Example:

"acme.com"

customMetadata

object

Arbitrary key-value metadata

Show child attributes

Response

Webhook received successfully

_metadata

object

required

Show child attributes

received

boolean

required

Whether the payload was received

connection

object | null

required

Connection details

Show child attributes

additionalData

object

Additional data about the processed event

Show child attributes

validationErrors

object

Per-field validation errors when the payload fails schema validation. Mirrors Zod's flatten() output so callers can map errors back to the offending fields.

Show child attributes