Sources API
Manage active webhook endpoints and their delivery/signature configuration.
Read and create
Source reads require SourceRead; writes require SourceWrite. API keys use sources:read or sources:write in addition to the current role. The organization comes from the authenticated context.
A simple creation explicitly sets verify_signature:false and omits provider/secret. It creates an active Generic source. destination_url is optional; async captures without one are stored but the original delivery is cancelled.
GET /v1/sources
GET /v1/sources/<source_id>
POST /v1/sourcesExample: unsigned source
{
"name": "Incoming webhooks",
"verify_signature": false,
"destination_url": "https://receiver.example/webhooks"
}Source fields
| Field | Meaning |
|---|---|
| id / name / provider | Stable source identity, display name and metadata provider |
| verify_signature | Signature mode; independent of active/paused state |
| signing_secret_configured / signing_secret_hint | Configuration metadata; never the secret or proof of verification |
| destination_url | Current destination for eligible async delivery |
| delivery_revision | Version to use in edits and replay preconditions |
| paused | New ingress can be explicitly dropped while paused |
| created_at | Creation timestamp |
Atomic edits and stale drafts
The dashboard sends the latest delivery_revision as expected_revision for every nonempty edit. Legacy API clients may omit this field, including for signature changes. When supplied, it rejects a revision changed by destination, pause, provider, secret or signature mode updates. A name-only change does not increment delivery_revision, so two concurrent renames are not detected by this precondition. Signature changes also use an internal compare-and-swap during the update.
Mode, provider and verification configuration are saved together. Enabling requires an implemented provider profile and valid configuration; the same provider can reuse its stored configuration. Changing provider while enabled requires a replacement. Check the provider directory for the exact fields and supported scheme.
The signing_secret string carries either the profile’s plain secret/public key or a JSON object encoded as a string. The dashboard builds structured configuration from labeled fields and stores it encrypted; source reads never return it. Preserve the exact field values required by the signature scheme. Stripe, Adyen, Checkout.com and Razorpay retain their existing outer-whitespace trimming behavior; new provider profiles preserve configured bytes.
Disabling verification preserves the provider and key. Send verify_signature:false with expected_revision, without a replacement secret. A stale revision returns 409; fetch, review and confirm explicitly.
PATCH /v1/sources/<source_id>Rotation, pause and deletion
Rotation requires verification on and a supported provider. Prefer the atomic PATCH for form edits protected by expected_revision.
Pause changes future capture and delivery eligibility while retaining history. Delete permanently removes the source and its captured events, retained content and delivery records. The ingress URL then stops accepting that source; deletion is not reversible.
POST /v1/sources/<source_id>/rotate-secret
DELETE /v1/sources/<source_id>Destination policy
Async outbound delivery requires an allowed HTTPS destination, normally port 443, without credentials or fragment. Private/loopback addresses and redirects are rejected by the sender. The replay dialog cannot bypass this policy.
A destination field can exist independently of async being enabled. A 202 from ingress is not proof that any configured receiver was called.