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.
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.Testing
We recommend performing all testing in your sandbox application. See Sandbox Environment.Local Development
While developing your endpoint, use Svix Play in relay mode to test and debug. Relay mode gives you a public URL that forwards events to your local server. Register that URL as an endpoint in Terminal’s dashboard.Sandbox Connections
Creating a sandbox connection triggers real events, such asconnection.created, sync.started, and sync.completed.
Replaying Events
If an event fired recently on an endpoint, you can replay it. In the webhooks section of Terminal’s dashboard, find the event under Message Attempts and click Replay. Replaying is useful for quick tests against your existing sandbox connections, such as re-running your handler after a code change without creating a new connection.Sending Signed Test Events
Some events, such as safety events, fire less often, which can make them difficult to test with replays. To test these events, send signed requests to your endpoint with Postman or a script. Copy your endpoint’s signing secret from the endpoint detail in the webhooks section of Terminal’s dashboard. Build the payload from the event’s schema in the API Reference. Sign each request with HMAC-SHA256 over{id}.{timestamp}.{body}: