Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt

Use this file to discover all available pages before exploring further.

Welcome to the Terminal Webhook API documentation! Terminal provides a webhook system that enables you to receive real-time notifications when specific events occur in our system. This basic guide will help you set up and use Terminal webhooks.

​
Overview

Webhooks are HTTP callbacks that get triggered when certain events occur. Terminal sends an HTTP POST request to a specified URL (your webhook endpoint) with a payload containing the event details. If you want to send Terminal events into tools like Slack or Microsoft Teams, webhooks are the supported integration point today. Terminal does not currently provide first-party Slack or Teams notification destinations, but you can forward webhook events to those tools through your own middleware or automation platform.

​
Event Types

Terminal webhook events have unique event types that indicate the action performed on a resource. Example event types include:
  • connection.created
  • sync.started
  • sync.completed
  • sync.failed
  • … and more
All webhook event schemas can be found in the API Reference

​
Setting Up a Webhook

  1. Create a webhook endpoint: Create an HTTP endpoint on your server that can listen for incoming POST requests. This endpoint should be able to parse and process webhook payloads.
  2. Add your webhook URL in Terminal: Register your webhook endpoint URL in Terminal’s dashboard. This is where Terminal will send the webhook events.
  3. Secure your webhook: To ensure incoming webhook requests originate from Terminal, implement signature validation. More details can be found below.

​
Webhook Payload

Webhook payloads contain information about the event in JSON format. A typical payload may look like this: 
{
  "id": "evt_01GV12VR4DJP70GD1ZBK0SDWFH",
  "type": "sync.completed",
  "detail": {
    "connection": {
      // connection details
    },
    "sync": {
      // sync details
    }
  }
}
Most events will provide the full entity of any related object in order to reduce the need to make additional requests back to Terminal.

​
Handling Webhook Events

When your webhook endpoint receives an event, it should:
  1. Verify the request’s authenticity: Check the signature or shared secret to ensure the request is from Terminal.
  2. Parse the payload: Parse the JSON payload from the request body to extract relevant information.
  3. Handle the event: Perform necessary actions based on the event type and data. For example, update your database or trigger ingestion pipelines.
  4. Respond with a 2xx status code: Acknowledge receipt of the webhook by responding with a 2xx HTTP status code. Terminal considers non-2xx responses as failed deliveries, and it may retry the webhook delivery.
  5. Handle retries: Terminal may retry webhook deliveries in case of failures. Ensure your endpoint is idempotent and can handle duplicate events gracefully.

​
Verifying Requests

Internally, our webhooks rely on Svix to handle events. Svix provides detailed instructions on how to verify the validity of webhook requests. Please refer to Svix’s documentation for guidance on confirming that webhook requests are genuine.
Failing to verify requests can leave your application vulnerable to various attacks, since your webhook endpoint is publicly accessible.

​
Troubleshooting and Monitoring

Always monitor and log webhook events and their responses for debugging and troubleshooting purposes. Terminal’s dashboard also provides information on webhook deliveries, including the status, any errors encountered and the ability to replay messages.
If you don’t see a specific event type available, please contact our support team for assistance. Some event types will require additional configuration.