Skip to main content
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:
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 within 30 seconds: Acknowledge receipt with an HTTP status from 200 to 299. Any other outcome is a failed delivery and is retried. See Retries.
  5. Treat delivery as at-least-once: The same event can arrive more than once. Make the handler idempotent and deduplicate on the event id.

Retries

Webhook delivery runs on Svix’s retry schedule. A delivery succeeds only when your endpoint returns a 2xx status code within 30 seconds. These outcomes are failures and follow the schedule below:
  • A status code outside 200–299, including 3xx redirects
  • A connection error
  • No response within 30 seconds
Respond as soon as the event is durably accepted, then process it asynchronously. Work that finishes after the 30 second window still counts as a failed delivery and is sent again. Each message is attempted on this schedule. Each delay starts when the previous attempt fails: Retries of one message carry the same payload id, so use that field to ignore duplicates. A later event can succeed while an earlier one is still retrying, so events can arrive out of order. Retries for the message stop when the response includes this header:
Send that header on a non-2xx response. A 2xx response completes the delivery. Sending webhook-delivery: disable disables the endpoint, so later messages are not delivered to it. Removing or disabling the endpoint in the dashboard also stops further attempts. See Svix delivery control for both headers. After the eighth attempt fails, the delivery is marked failed. Open the message in Terminal’s dashboard to inspect the attempts, replay that message, or recover failed messages starting from a given time. If every attempt to an endpoint fails across a 5 day period, Svix disables the endpoint. The period starts after multiple deliveries fail within 24 hours, with at least 12 hours between the first and last failure. Re-enable the endpoint from the dashboard once it can accept events again.

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. Automatic retries follow the retry schedule. Terminal’s dashboard also shows each delivery’s status and errors, and you can replay a message from there.
If you don’t see a specific event type available, please contact our support team for assistance. Some event types will require additional configuration.