Skip to main content

​
Using Webhooks to Keep External Applications Up-to-Date

Webhooks are a powerful way to receive real-time notifications from Coalesce Quality when specific events occur. This allows external applications to stay updated without constant polling, saving resources and ensuring timely updates.

​
Introduction to Webhooks

Coalesce Quality sends HTTP POST requests to a predefined URL whenever certain events occur, including issue lifecycle changes, incident notifications, or a simple ping to confirm that the webhook endpoint is reachable. Webhooks are defined by a schema that ensures the correct data structure is maintained. Each event has a specific payload format, allowing external applications to process the data accordingly. Latest schema definition is available as a JSON Schema and as HTML documentation.

​
Key Concepts

  • Event Types: Webhook events can represent different actions, such as ping, issue_created, issue_updated, issue_status_updated, issue_closed, incident_open, incident_closed, and incident_cancelled.
  • Payload Structure: Each event payload adheres to a defined JSON schema, ensuring consistency and reliability in the data received.
  • Callback Mechanisms: Webhooks can trigger specific commands or actions in the receiving application, making it possible to automate workflows based on incoming events.

​
Webhook Event Schema

The webhook event schema defines the structure of the payload sent for each event type:
  • workspace: Identifies the workspace where the event occurred.
  • event_id: A unique identifier for the event.
  • event_time: The time when the event occurred, formatted as a date-time string.
  • event_type: One of the specific event types (ping, issue_created, issue_updated, issue_status_updated, issue_closed, incident_open, incident_closed, incident_cancelled), each with its own structured payload.
  • callbacks: An array of callbacks that can be invoked based on the event, containing details such as url, action_name, and associated issues_command.

​
Event Types

​
Issue Events

  • Issue Created: Notifies that a new issue has been created. Contains an IssueSummary with details such as issue_id, title, description, status, trigger and affected entities.
  • Issue Updated: Indicates that an existing issue has been updated.
  • Issue Status Updated: Signals that the status of an issue has changed (e.g., investigating, expected, fixed, no action needed).
  • Issue Closed: Signals that an issue has been closed.

​
Incident Events

  • Incident Open: Notifies that a new incident has been opened. Contains an IncidentSummary with incident_id, title, description, and incident_url.
  • Incident Closed: Indicates that an incident has been closed.
  • Incident Cancelled: Signals that an incident has been cancelled.

​
Other Events

  • Ping: A simple test event sent during webhook setup to confirm the endpoint is functional. Payload contains a message.

​
Working with Webhook Events

To start using webhooks:
  1. Register a Webhook Endpoint: Provide a URL endpoint where Coalesce Quality can send events. Use Settings > Integrations > Add integration > Webhook.
  2. Handle Incoming Events: Set up your server to process incoming POST requests. Ensure that your endpoint correctly interprets the payload format defined in the webhook event schema. Return 2xx status codes to confirm receipt.
  3. Automate Actions: Use the event data to trigger specific actions in your application, such as updating a database, notifying users, or calling other APIs.

​
Sample Webhook Event Payload

Here’s an example of a webhook event payload for an issue created: 
{
  "workspace": "example_workspace",
  "event_id": "123456",
  "event_time": "2024-09-06T12:34:56Z",
  "event_type": "EVENT_TYPE_ISSUE_CREATED",
  "issue_created": {
    "issue": {
      "issue_id": "789",
      "issue_group_id": "group1",
      "issue_url": "https://app.synq.io/issues/789",
      "title": "Freshness check failed for orders table",
      "description": "Table has not been updated in the last 2 hours",
      "status": "ISSUE_STATUS_INVESTIGATING"
    }
  }
}