Skip to main content
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 for the management API and delivery activity endpoint.

​
Available events

See Event payloads 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 and Delivery behavior.

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