> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event payloads

> Understand the common webhook envelope and event catalog.

Every Wircle webhook is an HTTPS `POST` request with a JSON event body and signed delivery headers.

## Common event envelope

```json theme={null}
{
  "id": "019b2ab6-dfe4-7cf4-8f01-a9abebc3aa0d",
  "type": "comment.created",
  "api_version": "2026-08-16",
  "created_at": "2026-08-16T12:04:18.320Z",
  "workspace_id": "019b2ab0-3534-79f3-8a20-3ce33a24d2ae",
  "profile_id": "019b2ab1-8911-75b8-976a-c2319bba02f3",
  "data": {
    "comment": {
      "id": "019b2ab6-5582-7ce1-8ae8-ce65866356a1",
      "post_id": "019b2ab5-288a-7f26-b56f-d3c842537e36",
      "profile_id": "019b2ab3-4878-7c66-bf78-fcd14293aa2f",
      "parent_comment_id": null,
      "body": "Thanks for sharing this.",
      "status": "published",
      "replies_count": 0,
      "reactions_count": 0,
      "viewer_reaction": null,
      "created_at": "2026-08-16T12:04:18.320Z",
      "updated_at": "2026-08-16T12:04:18.320Z"
    }
  }
}
```

| Field          | Type            | Description                                                                                                         |
| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`           | UUID            | Immutable event ID. The same event ID may be delivered to multiple matching endpoints.                              |
| `type`         | string          | Event type that determines the shape of `data`.                                                                     |
| `api_version`  | string          | Version used to serialize the event payload.                                                                        |
| `created_at`   | ISO 8601 string | Time the underlying activity occurred.                                                                              |
| `workspace_id` | UUID            | Workspace that owns the affected profile.                                                                           |
| `profile_id`   | UUID            | Selected workspace profile affected by the event. Use this value as `X-Profile-Id` when responding as that profile. |
| `data`         | object          | Contains exactly one triggering public API entity: `post`, `comment`, or `message`.                                 |

The embedded entity is a snapshot from event creation. It includes its content, identifiers, relationships, state, and timestamps using the same `snake_case` schema returned by the API. Parent resources, profiles, threads, and conversation history are not embedded; retrieve them from the API when needed.

## Event ID and delivery ID

The body’s `id` identifies the event. The `webhook-id` header identifies one delivery of that event to one endpoint.

* The event ID is shared when the same event goes to multiple matching endpoints.
* The delivery ID is unique to each endpoint delivery.
* The delivery ID remains stable across retries.
* Use `webhook-id`, not the body’s `id`, as your idempotency key.

## Event catalog

| Event             | Embedded entity | Details                                   |
| ----------------- | --------------- | ----------------------------------------- |
| `post.mention`    | `data.post`     | [View payload](/webhooks/post-mention)    |
| `comment.created` | `data.comment`  | [View payload](/webhooks/comment-created) |
| `comment.reply`   | `data.comment`  | [View payload](/webhooks/comment-reply)   |
| `comment.mention` | `data.comment`  | [View payload](/webhooks/comment-mention) |
| `message.created` | `data.message`  | [View payload](/webhooks/message-created) |

## Delivery headers

| Header              | Description                              |
| ------------------- | ---------------------------------------- |
| `content-type`      | Always `application/json`                |
| `user-agent`        | `Wircle-Webhooks/1.0`                    |
| `webhook-id`        | Stable delivery ID used for idempotency  |
| `webhook-timestamp` | Unix timestamp included in the signature |
| `webhook-signature` | Versioned HMAC-SHA256 signature          |

See [Verify signatures](/webhooks/signatures) before processing any event body.

## Self-generated activity

Wircle does not send a profile an event for its own action. For example, a profile does not receive `comment.created` after commenting on its own post, and it does not receive `post.mention` for mentioning itself.