Skip to content

Setting up webhooks

When to use this guide: You are ready to register an HTTPS endpoint so OutboundSync can deliver Sync Monitoring events. Inbound paste URLs are Sources; this page is for product Webhooks. From a coding agent, prefer the Sync monitoring skill (writes only after confirmation).

Prerequisites

Section titled “Prerequisites”
  1. API access enabled on at least one connection (canUseApi), if you will manage webhooks via the API.
  2. Webhooks enabled on the account (canUseWebhooks) — otherwise webhook and events routes return 403.
  3. An account-scoped API key. Connection-scoped keys cannot call /api/v1/webhooks* (including GETs).
  4. The write scope on that key for create, update, delete, rotate-secret, test, and replay. Keys created in the admin app currently default to read; ask OutboundSync support for a write-scoped account key when you need mutations.

How to set up OutboundSync webhooks

Section titled “How to set up OutboundSync webhooks”

You can register a webhook in the admin app or via the API.

Dashboard

Section titled “Dashboard”
  1. Open Dashboard → Webhooks.
  2. Add an HTTPS URL and optional description.
  3. Choose event filters, or leave empty to receive all active events.
  4. Copy the signing secret immediately — it is shown once (oswhsec_…).
OutboundSync admin Webhooks section showing the HTTPS URL and description form, Add webhook button, and a table with one Active endpoint set to All events.
Register webhooks from Dashboard → Webhooks.
OutboundSync Webhook created dialog showing a signing secret that starts with oswhsec_, with Copy and Done buttons.
Copy the signing secret when the dialog appears; it is shown only once.

API

Section titled “API”
  1. Create an account-scoped key with write (see Creating API keys).
  2. POST /api/v1/webhooks with your HTTPS url, optional description, and optional enabledEvents.
  3. Store the returned secret (shown once).

Full request and response shapes: API v1 — Webhooks. Try it from Try the API when the live OpenAPI document lists these paths.

URL rules and limits

Section titled “URL rules and limits”
  • HTTPS only. Private, loopback, and link-local targets are rejected — including hostnames that resolve to those ranges over DNS.
  • An account may register at most 20 webhooks.
  • Soft-delete with DELETE /api/v1/webhooks/:id (or remove in the UI).

Next steps

Section titled “Next steps”
  1. Verify signatures on your endpoint.
  2. Send a test.ping before relying on production alerts.
  3. Review event types so you subscribe only to what you handle.