Webhooks

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.

​

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

​

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.

​

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.