Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

Every data source provisioned in realtime mode generates a public webhook URL. Third-party services — or your own systems — POST events to that URL, and Copass routes them to the right data source, dedups replays, and fans them out to triggers. This is how you push events from CI pipelines, internal services, custom monitors, or any system that already speaks HTTP into your sandbox without writing a polling loop.

​
What you can do

  • Receive events from third-party providers (GitHub, Slack, Stripe, etc.) onto an OAuth’d integration’s webhook URL — happens automatically when you connect.
  • Push events from your own systems to a custom data source’s webhook URL.
  • Validate inbound events with the signing secret returned at provisioning time.
  • Rotate the signing secret with a grace window (no dropped events during cutover).
  • Revoke a webhook permanently if it’s compromised.

​
How a webhook reaches an agent

your system  ──HTTP POST──►  https://api.copass.id/webhooks/{slug}
                                   │
                                   ▼
                         signing-secret validation
                                   │
                                   ▼
                          replay-dedup ledger
                            (provider_event_id, 7-day TTL)
                                   │
                                   ▼
                            data source ingest
                                   │
                                   ▼
                       trigger fan-out (matching agents fire)
The dedup ledger short-circuits redeliveries — Slack retries for 3 days, Stripe for 24 hours, and you don’t want every retry to fire your agents twice. Copass keys on provider_event_id and rejects duplicates before any work happens.

​
Provisioning a webhook

OAuth’d integrations get a webhook URL automatically when you connect. For custom data sources you provision them explicitly:

​
Via the Concierge

“Provision a custom data source called ci-events with a webhook URL.”
Returns the webhook URL and the signing secret. The signing secret is shown once — store it where your CI pipeline can read it.

​
Via the SDK

const source = await client.sources.register(sandboxId, {
  provider: 'custom',
  name: 'ci-events',
  ingestion_mode: 'realtime',
});

console.log(source.webhook_url);              // https://api.copass.id/webhooks/wh_...
console.log(source.webhook_signing_secret);   // shown ONCE — store it now

​
Sending events

Your code POSTs to the webhook URL with whatever JSON shape your downstream agents expect. The signing secret goes in an Authorization: Bearer header (or as configured at provision time): 
curl -X POST https://api.copass.id/webhooks/$WEBHOOK_SLUG \
  -H "Authorization: Bearer $WEBHOOK_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_event_id": "deploy-2026-04-29-abc",
    "event_type": "deploy.completed",
    "payload": { "service": "checkout", "version": "1.4.2" }
  }'
The provider_event_id is yours to choose — make it stable per logical event. Copass uses it to dedup replays. Successful POST returns 204 No Content. Validation failures return 401; replays return 200 with no body (idempotent).

​
Webhook lifecycle

A webhook row has three states:
StatusBehavior
activeAccepts events; signing-secret validated. The default.
rotatingAccepts events during the post-rotation grace window. Useful when you need to deploy a new secret to your senders without dropping events. New fan-out routes through the new row once it’s active.
revokedRejects with 410 Gone. Kept for audit; never deleted.

​
Rotating the signing secret

When a secret leaks or you’re rotating on a schedule:
“Rotate the signing secret on the ci-events webhook.”
The Concierge mints a new secret, marks the old row rotating, and gives you a window to redeploy. Once the new secret is everywhere, mark the old one revoked.

​
Common patterns

CI deploy stream

POST every successful deploy to a ci-events webhook. Agents react to deploys (post-mortem prep, changelog drafts, customer comms).

Internal service signals

Your billing system POSTs invoice events; an agent triages enterprise deals. No polling, no scraping.

Custom monitors

A datadog webhook fires on alert; an agent pulls the last 30 minutes of logs from connected sources and writes a summary.

Provider redelivery

OAuth’d integrations (Slack, GitHub) automatically deliver to webhook URLs Copass provisions on connect. No manual setup. See Data Sources.

​
Next steps

  • Data Sources — webhooks live on data sources in realtime mode.
  • Triggers — subscribe agents to webhook-driven events.
  • Ingestion — the alternate, push-based path when you’d rather call ingest directly.