Triggering External Activity Workflows with Webhooks

Audience: Technical Builders, Integrators, and Developers

Purpose: Explains how to use webhooks to trigger external workflows in response to completed or logged activities.

Overview

Webhooks notify external systems when Activities are logged. These notifications allow external systems to react in real time to changes in Kizen. Webhooks are configured per Activity Object, not globally. This allows you to control which Activities send webhook notifications and where those notifications are delivered.

Webhooks can be used for Activities to:

• Send notifications when an Activity is logged.

• Retrieve a full Record with a Logged Activity 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 Kizen.

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

• Triggering external workflows when an Activity is logged

• Synchronizing Activity history with external CRMs

• Sending real-time notifications to messaging or collaboration tools

• Reacting to Activity completion without polling the API

Note: Webhooks only work with logged Activities.

How Webhooks Work with Activities

Webhooks fire when a Logged Activity is created.

Each Activity Object includes a Default Submission Action, which determines what happens when an Activity of that type is submitted. You can configure the Activity Object to:

• Redirect the user after logging an Activity, or

• Trigger a webhook when the Activity is logged

When set to Trigger Webhook, Kizen sends a webhook request to the configured URL every time an Activity of that type is logged.

---

Event Type

Kizen currently supports a single webhook event for an activity:

Event	Description
activity.logged	Fired when a Logged Activity is created

Note: Webhooks are emitted only for logged Activities. Scheduled Activities do not trigger webhooks until they are logged.

Events that Trigger Webhooks

Webhooks are triggered when a Logged Activity is created, including when:

• A user manually creates a Logged Activity.

• A Scheduled Activity is completed, which then creates a Logged Activity in Kizen.

Events that do not Trigger Webhooks

Kizen does not currently send webhook notifications for:

• Scheduled Activity creation

• Scheduled Activity updates

• Scheduled Activity edits

• Scheduled or Logged Activity deletion

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 Activity Object.

For each Activity Object, you can:

• Set the Default Submission Action to trigger_webhook

• Define the webhook URL that receives notifications for that Activity type

• Subscribe to Activity webhook notifications.

Subscribing to Activity Webhook Notifications

Activity webhooks are configured in the Activity Object settings.

Enable webhook delivery

1. Open Activities.

2. Select the Activity you want to configure on the Activity Settings page.

3. Locate Default Submission Action. Change the value to Trigger Webhook.

4. Enter your Webhook URL where Kizen should send GET requests.

5. When you go back to the Activities page, your Activity will have webhooks enabled.

Webhook configuration are configured on the Activity Object and applies only to Activities logged using that type.

For more details, see:

• Activity Objects

• Activity Permissions

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 Activity, 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 Activity so you can retrieve the full record via the Activities API. For more information see: Viewing Logged Activity Details via API

---

Permissions & Data Access

Webhook notifications reference Logged Activities, but access to full Activity data depends on API permissions.

The Activities API enforces user and role-based access controls when retrieving Activity records. If the requesting integration lacks permission, the API may return an error. Read Activity Permissions for more details.

Example Use Case

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

When a team member logs an Activity 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, Kizen can push a notification the moment an Activity is logged so an external system like Slack can retrieve the Logged Activity 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 Activity's Default Submission Action to Trigger Webhook

   • Enter your Slack-processing endpoint

2. User logs an Activity

   • When this occurs, Kizen sends the Logged Activity payload to your webhook URL

3. Extract the relevant fields

   • With your service, extract the relevant fields, such as:

     • Activity 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 Timeline manually.

---

What's Next?

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

• Design your webhook endpoint to safely receive and process Activity events.

• Implement idempotent handling to prevent duplicate processing.

• Add logging and monitoring to track delivery success and failures.

• Extend your integration by linking Activity events to workflows, external systems, or analytics pipelines.

Related Topics

• Activities

• Activities Core Concepts

• Activities Data Model

• Activity Permissions

• Advanced Activity Rules

• Activities API & Webhooks