Kinabase Logo
Developer Documentation
Kinabase API

Webhooks

Use automation webhooks to send data from Kinabase to external services when events occur

Overview

Kinabase automations can trigger outbound webhooks (API calls) to send data to external services. This allows you to integrate Kinabase with third-party applications, trigger external workflows, and synchronise data across systems.

Outbound Webhooks This page covers outbound webhooks – HTTP requests sent from Kinabase to external URLs when automation triggers fire. For information about the Kinabase API (inbound), see Creating an App.

Setting Up a Webhook Automation

To create an automation that triggers a webhook, follow these steps:

  1. Open Automation Settings
    Navigate to Settings and select Automations under Organisation.

  2. Create a New Automation
    Click + Add Automation and give it a descriptive name (e.g., "Notify External CRM on New Lead").

  3. Define the Trigger
    Choose when the automation should run: when a record is added, updated, changes stage, becomes due, or is right-clicked.

  4. Add an API Call Step
    In the "Then" actions, add a step and select Call API (or "Webhook"). This creates an outbound HTTP request.

Configuring the Webhook

When configuring a webhook step, you can specify:

HTTP Method

Choose the HTTP method for the request:

  • GET – Retrieve data (default if no body)
  • POST – Send data (default if body provided)
  • PUT – Replace/update data
  • PATCH – Partially update data
  • DELETE – Remove data

URL

The destination URL for the webhook. This can include dynamic values from the triggering record using expressions.

Example: https://api.example.com/customers/{record.externalId}

URL Restrictions For security reasons, webhooks cannot call back to Kinabase URLs (app.kinabase.com or beta.kinabase.com).

Headers

Add custom headers to the request, such as authentication tokens or API keys. Each header consists of a name and value, and values can include dynamic expressions.

Example: Authorization: Bearer your-api-key

Request Body

For POST, PUT, and PATCH requests, you can specify a request body:

Content Types

  • text/plain – Simple text content
  • application/json – Structured JSON data

JSON Body Fields

When using JSON, you can define key-value pairs where each value is an expression. Supported types:

  • string – Text values
  • number – Numeric values
  • boolean – True/false values
  • json – Nested JSON objects or arrays

Example JSON Body

{
  "customerName": "Acme Corporation",
  "contactEmail": "john@acme.com",
  "orderValue": 1500.00,
  "isNewCustomer": true,
  "orderItems": [
    { "sku": "WIDGET-001", "quantity": 10 }
  ]
}

Handling Responses

Webhooks can capture the response from the external service and use it in subsequent automation steps.

Response Types

  • text – Capture the entire response body as a string
  • json – Parse the response as JSON and extract specific values

Response Schema (JSON)

When the response type is JSON, you can define a schema to extract specific values using JSON Pointers (RFC 6901). These values can then be mapped to automation fields for use in subsequent steps.

JSON Pointer Examples

  • /id – Root-level "id" property
  • /data/user/name – Nested property
  • /items/0/sku – First item in an array

Example Response Mapping

For a response like:

{
  "success": true,
  "data": {
    "externalId": "EXT-12345",
    "status": "created"
  }
}

You could use /data/externalId to extract "EXT-12345" and store it in a record field.

Error Handling

When a webhook request fails, the automation step will report an error. Common failure scenarios include:

  • Network errors – The external service is unreachable
  • HTTP 4xx/5xx responses – The external service returned an error
  • Invalid URL – The constructed URL is malformed
  • Timeout – The external service took too long to respond
Error Visibility When a webhook fails, the first 1,000 characters of the response body are captured in the error message to help with debugging. View automation logs to see detailed error information.

Best Practices

Secure Your Endpoints

Use authentication headers (API keys, Bearer tokens) to secure your webhook endpoints. Never expose sensitive credentials in URLs.

Handle Failures Gracefully

Design your external service to handle duplicate requests gracefully, as automations may retry failed steps.

Test Before Deploying

Use tools like webhook.site or RequestBin to test your webhook configuration before connecting to production services.

Monitor Automation Logs

Regularly check the automation history logs to identify and resolve any failed webhook calls. Right-click an automation and select History to view execution logs.

Use Cases

CRM Integration

When a new lead is added to Kinabase, automatically create a corresponding contact in your CRM system.

Notification Services

Send messages to Slack, Microsoft Teams, or other messaging platforms when important events occur.

Data Synchronisation

Keep external systems in sync by pushing updates whenever records change in Kinabase.

Workflow Triggers

Trigger external workflows in tools like Zapier, Make (Integromat), or custom systems when records reach specific stages.

Related Resources