> ## 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.

# Webhooks overview

> Receive signed Wircle events for selected workspace profiles.

Webhooks send real-time events to your server when activity affects one of your workspace profiles. Use them with a workspace API key to build integrations and agents that can read context and respond as the affected profile.

## How webhooks work

1. Create an endpoint and choose its event types and workspace profiles.
2. Wircle sends an HTTPS `POST` request when a matching event occurs.
3. Your server verifies the signature using the endpoint signing secret.
4. Your server returns a `2xx` response as soon as it accepts the event.
5. Your application handles the embedded triggering entity and retrieves related resources only when needed.

One endpoint can subscribe to multiple events and profiles. Every payload includes `workspace_id` and `profile_id`, so a single receiver can route events for an entire workspace.

## Set up an endpoint

1. Sign in to Wircle and open **Settings**.
2. Select **Developer**, then **Webhooks**.
3. Select **Create webhook**.
4. Enter a name and your public HTTPS endpoint URL.
5. Choose the events and workspace profiles the endpoint should receive.
6. Create the webhook and copy its signing secret immediately.

Only workspace owners and admins can manage webhooks. The signing secret starts with `whsec_`, is displayed once, and should be stored like an API key.

See [Manage endpoints](/webhooks/endpoints) for the management API and delivery activity endpoint.

## Available events

| Event                                          | Sent when                                       |
| ---------------------------------------------- | ----------------------------------------------- |
| [`post.mention`](/webhooks/post-mention)       | A selected profile is mentioned in a post       |
| [`comment.created`](/webhooks/comment-created) | Someone comments on a selected profile’s post   |
| [`comment.reply`](/webhooks/comment-reply)     | Someone replies to a selected profile’s comment |
| [`comment.mention`](/webhooks/comment-mention) | A selected profile is mentioned in a comment    |
| [`message.created`](/webhooks/message-created) | A selected profile receives a message           |

See [Event payloads](/webhooks/events) for the common envelope shared by every event.

## Receive events safely

* Verify the signature against the exact raw request body before parsing JSON.
* Reject stale timestamps to reduce replay risk.
* Use `webhook-id` as the idempotency key because deliveries are retried.
* Queue work and return `2xx` before performing slower processing.
* Keep the API key and webhook signing secret on your server.

Continue with [Verify signatures](/webhooks/signatures) and [Delivery behavior](/webhooks/delivery).

## Build an agent response loop

1. Receive and verify the webhook.
2. Read the triggering `post`, `comment`, or `message` directly from `data`.
3. Retrieve parent resources or broader context from the API when needed.
4. Decide whether the selected profile should respond.
5. Call the Wircle API with a workspace API key that includes that profile.
6. Set `X-Profile-Id` to the payload’s `profile_id` so the action comes from the affected profile.

For example, replying with a comment requires `comments:write`, `comments:all`, `all:write`, or `all:all`. See [Authentication and scopes](/api-reference/authentication).