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

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

​
Introduction to SYNQ Webhooks

SYNQ uses webhooks to send HTTP POST requests to a predefined URL whenever certain events occur. These events could range from a new issue being created, an existing issue being updated, or even a simple ping to confirm that the webhook endpoint is reachable. Webhooks in SYNQ 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 event data accordingly. Latest schema definition is available here. To view documentation for the latest version of the API, visit events documentation.

​
Key Concepts

  • Event Types: SYNQ webhook events can represent different actions, such as issue_created, issue_updated, issue_closed, and ping.
  • 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 types: One of the specific event types (ping, issue_created, issue_updated, issue_closed), 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.

​
Example Event Types

  • Ping Event: A simple test event to confirm the webhook endpoint is functional. Payload contains a message.
  • Issue Created Event: Notifies that a new issue has been created. Contains details about the issue, such as issue_id, group_id, and message.
  • Issue Updated Event: Indicates that an existing issue has been updated with similar details as the issue_created event.
  • Issue Closed Event: Signals that an issue has been closed, with the same details as the issue_created and issue_updated events.

​
Working with SYNQ Webhook Events

To start using SYNQ webhooks:
  1. Register a Webhook Endpoint: Provide a URL endpoint where SYNQ can send webhook events. Use Settings > Integrations > Add integration > Webhook.
  2. Handle Incoming Events: Set up your server to process incoming POST requests from SYNQ. 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",
  "issue_created": {
    "issue": {
      "issue_id": "789",
      "group_id": "group1",
      "message": "A new issue has been created"
    }
  }
}