Integration API
Create destinations, test delivery, inspect attempts, replay events, and rotate signing secrets.
Integration writes require Administrator authority. Delivery is at least once and independently owned by the receiver.
Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.
Create an integration
/organizations/{organization_id}/integrationsCreates a disabled integration. The secret-bearing destination is write-only and omitted from subsequent reads.
namestringrequiredDisplay name; does not change resource identity.
typestringrequiredReceiver transport.
destinationstringrequiredHTTPS receiver URL, PagerDuty routing destination, or TLS syslog host:port as selected.
credentialstringoptionalWrite-only receiver secret when required by the selected transport.
event_typesstring[]requiredExplicit subscribed event types.
redactionstringoptionalUnmasked delivery requires a sensitive-data grant.
maskedReturns integration ID, masked destination, disabled initial state, and ETag. Webhook signing secrets are returned only through the protected creation result.
Read an integration
/organizations/{organization_id}/integrations/{integration_id}Returns type, masked destination, subscriptions, enabled state, health, and secret version IDs; no raw credentials.
Returns data and request_id.
Enable or disable delivery
/organizations/{organization_id}/integrations/{integration_id}Updates delivery routing. Requires If-Match. Disabling stops new deliveries; already delivered external messages remain.
enabledbooleanrequiredWhether to route new deliveries. true enables routing; false stops new deliveries. Existing external messages remain unchanged.
Returns integration and ETag. A separate test confirms receiver readiness.
Test a destination
/organizations/{organization_id}/integrations/{integration_id}/testSends a synthetic event labeled as a test. Send an empty object. The test cannot create a real response action.
Returns a delivery operation. Receiver failure is recorded separately from integration configuration.
List delivery attempts
/organizations/{organization_id}/integrations/{integration_id}/deliveriesReturns attempt IDs, stable event ID, timing, receiver response, and redacted failure details. Standard limit and cursor apply. Unknown filters return 422.
event_idstringoptionalFilter original event identity.
statestringoptionalDelivery state.
Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.
Replay a failed delivery
/organizations/{organization_id}/integrations/{integration_id}/deliveries/{delivery_id}/retryCreates another attempt for the same event ID after current authorization and destination checks. It does not create another detection.
reasonstringrequiredAudited justification. Empty values are invalid.
Returns new attempt and operation. The receiver must deduplicate the stable event ID.
Rotate a signing secret
/organizations/{organization_id}/integrations/{integration_id}/rotate-secretRotates a webhook signing secret. Requires If-Match; other transports return 422.
overlap_secondsintegeroptionalInterval during which both signing-secret versions remain valid. Configure the receiver to accept either valid version until this interval ends.
3600rule60–86400 secondsReturns the new secret once, version IDs, and previous-version retirement time. Deploy receiver verification before ending overlap.