Triggering External Activity Workflows with Webhooks
Audience: Developers and Solution Architects
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:
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.
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_webhookDefine 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
Open Activities.
Select the Activity you want to configure on the Activity Settings page.
Locate Default Submission Action. Change the value to Trigger Webhook.
Enter your Webhook URL where Kizen should send GET requests.
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:
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
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.
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
Enable webhook delivery
Set the Activity's Default Submission Action to Trigger Webhook
Enter your Slack-processing endpoint
User logs an Activity
When this occurs, Kizen sends the Logged Activity payload to your webhook URL
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)
Format the Slack message
For example, you can write: Alex Rivera logged a Sales Call with Maria Thompson.
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.
Last updated
Was this helpful?