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.createdsync.startedsync.completedsync.failed- … and more
Setting Up a Webhook
- 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.
- Add your webhook URL in Terminal: Register your webhook endpoint URL in Terminal’s dashboard. This is where Terminal will send the webhook events.
- 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:Handling Webhook Events
When your webhook endpoint receives an event, it should:- Verify the request’s authenticity: Check the signature or shared secret to ensure the request is from Terminal.
- Parse the payload: Parse the JSON payload from the request body to extract relevant information.
- Handle the event: Perform necessary actions based on the event type and data. For example, update your database or trigger ingestion pipelines.
-
Respond with a 2xx status code within 30 seconds: Acknowledge receipt with an HTTP status from
200to299. Any other outcome is a failed delivery and is retried. See Retries. -
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 a2xx status code within 30 seconds. These outcomes are failures and follow the schedule below:
- A status code outside
200–299, including3xxredirects - A connection error
- No response within 30 seconds
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:
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.