# Triggering External Activity Workflows with Webhooks

{% hint style="success" %}
**Audience:** Developers and Solution Architects

**Purpose:** Explains how to use webhooks to trigger external workflows in response to completed or logged activities.
{% endhint %}

## Overview

Webhooks notify external systems when <code class="expression">space.vars.activities</code> are logged. These notifications allow external systems to react in real time to changes in Kizen. Webhooks are configured per <code class="expression">space.vars.activity</code> Object, not globally. This allows you to control which <code class="expression">space.vars.activities</code> send webhook notifications and where those notifications are delivered.

Webhooks can be used for Activities to:

* Send notifications when an <code class="expression">space.vars.activity</code> is logged.
* Retrieve a full Record with a Logged <code class="expression">space.vars.activity</code> ID.
* Provide necessary context to trigger downstream workflows in external systems

### When to use Webhooks for Activities

Use webhooks when external systems need to respond immediately to work that has occurred in <code class="expression">space.vars.Kizen\_company\_name</code>.

Webhooks are event-driven and designed for near real-time integrations. Typical scenarios include:

* Triggering external workflows when an <code class="expression">space.vars.activity</code> is logged
* Synchronizing <code class="expression">space.vars.activity</code> history with external CRMs
* Sending real-time notifications to messaging or collaboration tools
* Reacting to <code class="expression">space.vars.activity</code> completion without polling the API

{% hint style="info" %}
**Note**: Webhooks only work with logged Activities.
{% endhint %}

### How Webhooks Work with Activities

Webhooks fire when a Logged <code class="expression">space.vars.activity</code> is created.

Each <code class="expression">space.vars.activity</code> Object includes a Default Submission Action, which determines what happens when an <code class="expression">space.vars.activity</code> of that type is submitted. You can configure the <code class="expression">space.vars.activity</code> Object to:

* Redirect the user after logging an <code class="expression">space.vars.activity</code>, or
* Trigger a webhook when the <code class="expression">space.vars.activity</code> is logged

When set to Trigger Webhook, <code class="expression">space.vars.Kizen\_company\_name</code> sends a webhook request to the configured URL every time an Activity of that type is logged.&#x20;

***

## Event Type

<code class="expression">space.vars.Kizen\_company\_name</code> currently supports a single webhook event for an activity:

| Event             | Description                                                                        |
| ----------------- | ---------------------------------------------------------------------------------- |
| `activity.logged` | Fired when a Logged <code class="expression">space.vars.activity</code> is created |

{% hint style="info" %}
**Note:** Webhooks are emitted only for Logged <code class="expression">space.vars.activities</code>. Scheduled <code class="expression">space.vars.activities</code> do not trigger webhooks until they are logged.
{% endhint %}

{% columns %}
{% column %}

### Events that Trigger Webhooks

Webhooks are triggered when a Logged <code class="expression">space.vars.activity</code> is created, including when:

* A user manually creates a Logged <code class="expression">space.vars.activity</code>.
* A Scheduled <code class="expression">space.vars.activity</code> is completed, which then creates a Logged <code class="expression">space.vars.activity</code> in Kizen.
  {% endcolumn %}

{% column %}

### Events that do not Trigger Webhooks

<code class="expression">space.vars.Kizen\_company\_name</code> does **not** currently send webhook notifications for:

* Scheduled <code class="expression">space.vars.activity</code> creation
* Scheduled <code class="expression">space.vars.activity</code> updates
* Scheduled <code class="expression">space.vars.activity</code> edits
* Scheduled or Logged <code class="expression">space.vars.activity</code> deletion
  {% endcolumn %}
  {% endcolumns %}

Additional webhook events for Scheduled or Logged Activities may be added in the future. Automation triggers are currently available for Scheduled Activity Overdue events.

***

## About Configuration

Webhooks are configured on the <code class="expression">space.vars.activity</code> Object.

For each <code class="expression">space.vars.activity</code> Object, you can:

* Set the Default Submission Action to `trigger_webhook`
* Define the webhook URL that receives notifications for that <code class="expression">space.vars.activity</code> type
* Subscribe to <code class="expression">space.vars.activity</code> webhook notifications.

<details>

<summary>Subscribing to <code class="expression">space.vars.activity</code> Webhook Notifications</summary>

<code class="expression">space.vars.activity</code> webhooks are configured in the <code class="expression">space.vars.activity</code> Object settings.

<div data-with-frame="true"><figure><img src="/files/ck2pTQ89YK3QZLwZZPh7" alt=""><figcaption></figcaption></figure></div>

#### Enable webhook delivery

1. Open <code class="expression">space.vars.activities</code>.
2. Select the <code class="expression">space.vars.activity</code> you want to configure on the <code class="expression">space.vars.activity</code> Settings page.
3. Locate **Default Submission Action**. Change the value to **Trigger Webhook.**&#x20;
4. Enter your **Webhook URL** where <code class="expression">space.vars.Kizen\_company\_name</code> should send GET requests.
5. When you go back to the <code class="expression">space.vars.activities</code> page, your <code class="expression">space.vars.activity</code> will have webhooks enabled.

</details>

Webhook configuration are configured on the <code class="expression">space.vars.activity</code> Object and applies only to <code class="expression">space.vars.activities</code> logged using that type.

For more details, see:

* [Activity Objects](/docs/concepts/activities/activities-data-model.md#activity-objects)
* [Activity Permissions](/docs/concepts/activities/activity-permissions.md)

### Webhook Delivery Behavior

Webhooks are delivered as HTTP requests to the URL configured on the object.

**Delivery details:**

* Method: GET
* Content type: JSON (`application/json`)
* Trigger frequency: One request per logged activity
* Delivery timing: Near real time, but not guaranteed
* Delivery model: Asynchronous

If a webhook delivery fails (for example, the endpoint returns a non-2xx response), a failure notification is generated. Webhook deliveries are not automatically retried.

**Ordering and reliability considerations**\
Webhook notifications are not guaranteed to arrive in strict chronological order and may occasionally be delayed. Your webhook handler should be designed to tolerate:

* Out-of-order delivery
* Delayed delivery

Each webhook should be treated as a signal to fetch the authoritative data from the API rather than relying solely on the payload.

### Webhook Security and Verification

Webhooks do not currently include request signatures or shared secrets. For this reason, webhook notifications should be treated as **event signals only**, not as trusted business data.

Each webhook payload includes an identifier, but consumers must retrieve the full activity details through the API using authenticated requests. This ensures permissions are enforced and that processing only occurs for data the consumer is authorized to access.

Because authoritative data is not delivered in the webhook itself, endpoints only need to perform basic structural validation on incoming requests. Additional verification mechanisms may be introduced in future updates.

### Operational Considerations

Webhooks are delivered using an at-least-once delivery model. Each webhook corresponds to a single Logged <code class="expression">space.vars.activity</code>, but deliveries may occur more than once in certain failure scenarios. Consumers should treat webhook handling as idempotent and de-duplicate events using the `logged_activity_id`.

A webhook delivery is considered successful when the receiving endpoint responds with a **2xx HTTP status code**. Webhook endpoints should respond quickly and defer any long-running processing to background jobs.

Webhook requests may evolve over time as additional fields or event types are introduced. Breaking changes will be versioned or communicated through developer documentation updates. Consumers should avoid relying on undocumented fields.

***

## Viewing Logged Activity Details

Webhooks are delivered as HTTP GET requests. The request includes query parameters that identify the Logged <code class="expression">space.vars.activity</code> so you can retrieve the full record via the <code class="expression">space.vars.activities</code> API. For more information see: [Viewing Logged Activity Details via API](/docs/concepts/activities/activities-api-and-webhooks/view-logged-activity-details-api.md)

{% hint style="info" %}
Activity field data is not included in webhook payloads. Webhooks provide the logged activity ID only. To retrieve Activity field values—including Activity-specific custom fields—call the Logged Activity endpoint with that ID.
{% endhint %}

***

## Permissions & Data Access

Webhook notifications reference Logged <code class="expression">space.vars.activities</code>, but access to full <code class="expression">space.vars.activity</code> data depends on API permissions.

The <code class="expression">space.vars.activities</code> API enforces user and role-based access controls when retrieving <code class="expression">space.vars.activity</code> records. If the requesting integration lacks permission, the API may return an error. Read [Activity Permissions](/docs/concepts/activities/activity-permissions.md) for more details.

<details>

<summary>Example Use Case</summary>

Many teams coordinate their work using messaging platforms such as Slack.

When a team member logs an <code class="expression">space.vars.activity</code> like a call, an email, or a follow-up email, the rest of the team often needs to know immediately that the activity happened. Without webhooks, teams would need to refresh the application, poll the API, or wait for updates to be shared manually.

With a webhook integration, <code class="expression">space.vars.Kizen\_company\_name</code> can push a notification the moment an <code class="expression">space.vars.activity</code> is logged so an external system like Slack can retrieve the Logged <code class="expression">space.vars.activity</code> then send a Slack message, update your dashboards, or trigger any follow-up workflows automatically.

### Creating Slack messages when Activities are logged

1. Enable webhook delivery
   * Set the <code class="expression">space.vars.activity</code>'s Default Submission Action to **Trigger Webhook**
   * Enter your Slack-processing endpoint
2. User logs an <code class="expression">space.vars.activity</code>
   * When this occurs, <code class="expression">space.vars.Kizen\_company\_name</code> sends the Logged <code class="expression">space.vars.activity</code> payload to your webhook URL
3. Extract the relevant fields
   * With your service, extract the relevant fields, such as:
     * <code class="expression">space.vars.activity</code> type (`activity_object.api_name`)
     * Logged by (`logged_by.display_name`)
     * Associated Contact (`associated_entities[0].display_name`)
     * Notes (`notes`)
4. Format the Slack message
   * For example, you can write: Alex Rivera logged a Sales Call with Maria Thompson.
5. Post the Slack message

#### Result

Your team gets instant visibility into important interactions, without polling the API or checking the <code class="expression">space.vars.timeline</code> manually.

</details>

***

## What's Next?

Once you understand how webhooks work for Activities, you can:

* Design your webhook endpoint to safely receive and process <code class="expression">space.vars.activity</code> events.
* Implement idempotent handling to prevent duplicate processing.
* Add logging and monitoring to track delivery success and failures.
* Extend your integration by linking <code class="expression">space.vars.activity</code> events to workflows, external systems, or analytics pipelines.

<details>

<summary>Related Topics</summary>

* [Activities](/docs/concepts/activities.md)
* [Activities Core Concepts](/docs/concepts/activities/activities-core-concepts.md)
* [Activities Data Model](/docs/concepts/activities/activities-data-model.md)
* [Activity Permissions](/docs/concepts/activities/activity-permissions.md)
* [Advanced Activity Rules](/docs/concepts/activities/advanced-activity-rules.md)
* [Activities API & Webhooks](/docs/concepts/activities/activities-api-and-webhooks.md)

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.kizen.com/docs/concepts/activities/activities-api-and-webhooks/triggering-external-activity-workflows-with-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.