Consuming webhooks

When your app receives a webhook request from Featurebase, check the topic attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a post, comment, etc.

Basic payload structure

{
  "id": "notif_0193a6e6-fb6b-78ef-b71f-15008d9f9cde",
  "object": "notification_event",
  "topic": "post.updated",
  "data": {
    "object": "notification_event_data",
    "item": {
      "id": "6755c4afb12a37dffa6319b0",
      "object": "post",
      "title": "My new title"
    },
    "changes": [
      {
        "field": "title",
        "oldValue": "My old title",
        "newValue": "My new title"
      }
    ]
  }
}

In the example above, a post was updated, and the payload type is a notification_event_data. Notice how the changes array contains the old and new values for the changed fields.

Full payload structure

Each webhook event includes:

Field	Description
object	Always "notification_event"
id	Unique identifier for the webhook event (prefixed with notif_)
topic	The specific event type
organizationId	Your organization’s unique identifier
webhookId	ID of the webhook configuration
createdAt	Timestamp when the event occurred
deliveryStatus	Current delivery status of the webhook
conversationId	Short ID of the conversation (conversation topics only)
conversationUrl	Direct link to the conversation in the dashboard (conversation topics only)
data	Contains the event details
data.object	Always "notification_event_data"
data.item	The resource that triggered the event
data.changes	For update events, an array of { field, oldValue, newValue } objects showing changes

The data.item object structure varies based on the event type. For conversation topics, it is either a full Conversation object (for conversation-level topics) or a single ConversationPart object (for message-level topics). See Topic types for details on which topics send which object.

Nova format

Nova webhook payloads use the standardized API format:

Aspect	Nova Format
Type identifier	object: 'resource_name'
Board reference	boardId
Author	author: { id, name, profilePicture }
Status	status: { object: 'post_status', ... }
Tags	tags: [...]
Comments enabled	features.commentsEnabled
Access control	access.userIds, access.companyExternalIds
Timestamps	createdAt, updatedAt
Pinned	isPinned

Example: post payload

{
  "object": "notification_event",
  "id": "notif_0193a70c-3015-757c-a260-22ae37c86608",
  "topic": "post.updated",
  "organizationId": "6595518396205e06b897ad65",
  "webhookId": "675346db13af7340748ce850",
  "createdAt": "2024-12-08T16:13:34.102Z",
  "deliveryStatus": "pending",
  "data": {
    "object": "notification_event_data",
    "item": {
      "object": "post",
      "id": "67546dfb6e1363426b90707f",
      "title": "New title",
      "content": "<p>New content</p>",
      "boardId": "6755d0970b5d5b1fefdf54f4",
      "status": { "object": "post_status", "name": "Completed", "color": "Green", "type": "completed" },
      "author": { "id": "5fef50c5e9458a0012f82456", "name": "Admin", "email": "admin@example.com" },
      "createdAt": "2024-12-08T17:06:30.577Z",
      "updatedAt": "2024-12-08T17:06:30.577Z"
    },
    "changes": [
      { "field": "title", "oldValue": "Old title", "newValue": "New title" },
      { "field": "content", "oldValue": "<p>Old content</p>", "newValue": "<p>New content</p>" }
    ]
  }
}

Example: conversation-level payload

Conversation-level topics (like conversation.admin.closed) send a full Conversation object as data.item and may include a data.changes array. The conversationParts array is not included in webhook payloads — use the Conversations API to fetch messages if needed. The envelope also includes conversationId and conversationUrl.

{
  "object": "notification_event",
  "id": "notif_0194b7f8-ac3d-79ef-c82g-26119e0a0def",
  "topic": "conversation.admin.closed",
  "organizationId": "6595518396205e06b897ad65",
  "conversationId": "12345",
  "conversationUrl": "https://yourorg.featurebase.app/dashboard/inbox/all/conversation/12345",
  "webhookId": "675346db13af7340748ce850",
  "createdAt": "2025-06-15T14:22:01.000Z",
  "deliveryStatus": "pending",
  "data": {
    "object": "notification_event_data",
    "item": {
      "object": "conversation",
      "id": "12345",
      "title": "Help with billing",
      "state": "closed",
      "priority": false,
      "adminAssigneeId": "5fef50c5e9458a0012f82456",
      "teamAssigneeId": null,
      "participants": [{ "type": "customer", "id": "507f1f77bcf86cd799439012" }],
      "source": { "object": "message_source", "bodyHtml": "<p>I need help with my billing.</p>" },
      "readReceipts": [],
      "createdAt": "2025-06-15T14:00:00.000Z",
      "updatedAt": "2025-06-15T14:22:00.000Z"
    },
    "changes": [{ "field": "state", "oldValue": "open", "newValue": "closed" }]
  }
}

Example: message-level payload

Message-level topics (like conversation.admin.replied) send a single ConversationPart as data.item. They never include data.changes. The specific part variant depends on the partType discriminator.

{
  "object": "notification_event",
  "id": "notif_0194b802-1a5f-79ef-d93h-37220f1b1egh",
  "topic": "conversation.admin.replied",
  "organizationId": "6595518396205e06b897ad65",
  "conversationId": "12345",
  "conversationUrl": "https://yourorg.featurebase.app/dashboard/inbox/all/conversation/12345",
  "webhookId": "675346db13af7340748ce850",
  "createdAt": "2025-06-15T14:22:01.000Z",
  "deliveryStatus": "pending",
  "data": {
    "object": "notification_event_data",
    "item": {
      "object": "conversation_part",
      "id": "3",
      "partType": "admin_msg",
      "bodyHtml": "<p>I've updated your billing details.</p>",
      "bodyMarkdown": "I've updated your billing details.",
      "channel": "messenger",
      "author": { "type": "admin", "id": "5fef50c5e9458a0012f82456", "name": "Support Agent" },
      "redacted": false,
      "createdAt": "2025-06-15T14:22:00.000Z",
      "updatedAt": "2025-06-15T14:22:00.000Z"
    }
  }
}

Next steps

• Topic types - View all available webhook event types