Webhooks overview - Inbox API

How webhooks work

Webhooks send HTTP POST requests to your server when events occur in Inbox — a new message arrives, a thread is assigned, a campaign target replies, and more. Instead of polling the API for changes, register a webhook URL and Inbox pushes events to you as they happen.

Your server ◀── POST /your-webhook ── Inbox

Configure webhooks in Settings → Webhooks in your Inbox dashboard. You choose which event types each webhook receives.

Event envelope

Every webhook delivery wraps event-specific data in a consistent envelope:

string

required

Unique event ID. Use this to deduplicate deliveries.

number

required

Monotonically increasing sequence number per team. Use this to detect missed events and maintain ordering.

string

required

The team this event belongs to.

string

required

The event type in resource.action format (e.g., thread.created, message.created).

string

required

ISO 8601 timestamp of when the event occurred.

string

required

Schema version. Currently always "1.0".

object

required

The event payload. Structure varies by event type — see individual event pages for details.

{
  "id": "ck9v2m5nj0xp4wq7ybftrae8",
  "seq": 42,
  "teamId": "hzcai5t59nn9vsck3rbuepyg",
  "type": "thread.created",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "version": "1.0",
  "data": {
    "thread": { "..." },
    "prospect": { "..." }
  }
}

Supported event types

Inbox supports 33 event types across 7 categories. Subscribe to individual events or entire categories.

Thread events

Event	Description
`thread.created`	A new thread is created
`thread.deleted`	A thread is deleted
`thread.assigned`	A thread is assigned to a team member. Deprecated — use `prospect.assigneeChanged` instead.
`thread.unassigned`	A thread is unassigned from a team member. Deprecated — use `prospect.assigneeChanged` instead.
`thread.archived`	A thread is marked as done
`thread.unarchived`	A thread is reopened
`thread.typing`	A prospect is typing in an X Chat thread

Message events

Event	Description
`message.created`	A message is sent or received
`message.edited`	A message is edited
`message.deleted`	A message is deleted
`message.reactionAdded`	A reaction is added to a message
`message.reactionRemoved`	A reaction is removed from a message

Prospect events

Event	Description
`prospect.created`	A new prospect is created
`prospect.statusChanged`	A prospect’s pipeline status changes
`prospect.tagsChanged`	Tags are added or removed from a prospect
`prospect.notesChanged`	A prospect’s notes are updated
`prospect.valuationChanged`	A prospect’s valuation changes
`prospect.assigneeChanged`	A prospect’s assignee is set, changed, or cleared
`prospect.enriched`	A prospect is enriched with fresh platform data

Tag events

Event	Description
`tag.created`	A new tag is created
`tag.updated`	A tag is updated
`tag.deleted`	A tag is deleted

Status events

Event	Description
`status.created`	A new pipeline status is created
`status.updated`	A pipeline status is updated
`status.deleted`	A pipeline status is deleted

Campaign events

Event	Description
`campaign.created`	A new campaign is created
`campaign.started`	A campaign is started
`campaign.paused`	A campaign is paused
`campaign.resumed`	A campaign is resumed
`campaign.completed`	A campaign completes

Target events

Event	Description
`target.contacted`	A campaign target receives the initial message
`target.followUpSent`	A follow-up message is sent to a target
`target.replied`	A campaign target replies

Delivery behavior

Inbox attempts delivery once with no retries. Responses are not checked — delivery is fire-and-forget. Use the Events API to fetch any events your webhook missed. Events are retained for 7 days.

Handling webhooks

Your endpoint should:

Deduplicate using event.id in case of rare duplicate deliveries
Handle events idempotently
Track the latest seq value so you can backfill missed events via the Events API

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/inbox', async (req, res) => {
  const event = req.body;

  // Return 200 immediately
  res.sendStatus(200);

  // Process asynchronously
  switch (event.type) {
    case 'message.created':
      await handleNewMessage(event.data);
      break;
    case 'prospect.assigneeChanged':
      await handleAssigneeChanged(event.data);
      break;
    case 'prospect.statusChanged':
      await syncProspectToCRM(event.data);
      break;
  }
});

app.listen(3000);

const express = require('express');

const app = express();
app.use(express.json());

app.post('/webhooks/inbox', async (req, res) => {
  const event = req.body;

  // Return 200 immediately
  res.sendStatus(200);

  // Process asynchronously
  switch (event.type) {
    case 'message.created':
      await handleNewMessage(event.data);
      break;
    case 'prospect.assigneeChanged':
      await handleAssigneeChanged(event.data);
      break;
    case 'prospect.statusChanged':
      await syncProspectToCRM(event.data);
      break;
  }
});

app.listen(3000);

Events API

The Events API lets you replay events from the last 7 days. Use it to recover missed webhooks or backfill data.

cURL

curl "https://inboxapp.com/api/v1/events?afterSeq=0&limit=100" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

Response:

{
  "events": [
    {
      "id": "ck9v2m5nj0xp4wq7ybftrae8",
      "seq": 1,
      "teamId": "hzcai5t59nn9vsck3rbuepyg",
      "type": "message.created",
      "timestamp": "2025-01-15T10:30:00.000Z",
      "version": "1.0",
      "data": { }
    }
  ],
  "hasMore": true,
  "lastSeq": 100
}

Parameter	Type	Description
`afterSeq`	`number`	Return events after this sequence number. Omit to start from the beginning.
`limit`	`number`	Maximum events to return. Default: `100`, max: `1000`.

Use lastSeq from the response as afterSeq in your next request to paginate through all events.

Store the last processed seq value persistently. Run a background job that periodically polls the Events API using your stored seq to catch anything your webhook handler missed.

Missed event recovery

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://inboxapp.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.INBOX_API_TOKEN}`,
  },
});

async function syncMissedEvents(lastSeq: number): Promise<number> {
  let afterSeq = lastSeq;

  while (true) {
    const { data } = await client.get('/events', {
      params: { afterSeq, limit: 1000 },
    });

    for (const event of data.events) {
      await processEvent(event); // Deduplicate using event.id
    }

    if (!data.hasMore) {
      return data.lastSeq ?? afterSeq;
    }

    afterSeq = data.lastSeq;
  }
}

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://inboxapp.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.INBOX_API_TOKEN}`,
  },
});

async function syncMissedEvents(lastSeq) {
  let afterSeq = lastSeq;

  while (true) {
    const { data } = await client.get('/events', {
      params: { afterSeq, limit: 1000 },
    });

    for (const event of data.events) {
      await processEvent(event); // Deduplicate using event.id
    }

    if (!data.hasMore) {
      return data.lastSeq ?? afterSeq;
    }

    afterSeq = data.lastSeq;
  }
}

Next steps

Thread events

Get notified about new, assigned, and archived threads

Message events

Track messages, edits, and reactions

Campaign events

Monitor campaign lifecycle changes

Migrating from legacy webhooks

Update from the old event format

​How webhooks work

​Event envelope

​Supported event types

​Thread events

​Message events

​Prospect events

​Tag events

​Status events

​Campaign events

​Target events

​Delivery behavior

​Handling webhooks

​Events API

​Missed event recovery

​Next steps

Thread events

Message events

Campaign events

Migrating from legacy webhooks

How webhooks work

Event envelope

Supported event types

Thread events

Message events

Prospect events

Tag events

Status events

Campaign events

Target events

Delivery behavior

Handling webhooks

Events API

Missed event recovery

Next steps