Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Create a webhook URL Beta

POST/api/v1/connections/{connection_id}/trigger-ingress

This endpoint is in beta. Its request and response may change.

Creates the webhook URL the app sends this connection's events to. Register the URL in your app's settings at the provider, then set the signing secret. Only a connection whose app has a webhook trigger can have one. If the connection already has a URL, it's returned unchanged, so retrying is safe. Keep the URL private.

This page as markdownTriggers overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Path parameters

connection_idstringrequired
ID of the connection, in this environment. Up to 64 characters.

Response 200

connection_idstring
ID of the connection this webhook URL belongs to.
idstring
Unique identifier of the connection's webhook endpoint.
masked_signing_secretstring
The stored secret with all but its last four characters replaced, or every character replaced for a secret of 8 characters or fewer. Empty when none is configured. Enough to compare against the secret the provider's app configuration shows, and never enough to sign with.
previous_signing_secret_expires_atstring
When the previous secret stops being accepted even if the rotation is never confirmed: 24 hours after the rotation started. Absent when no rotation is in progress.
rotation_in_progressboolean
Whether the previous signing secret is still accepted alongside the current one. True from the moment a different secret replaces a stored one until the rotation is confirmed, or until previous_signing_secret_expires_at passes.
signing_secret_configuredboolean
Whether a signing secret is stored. While false, every event sent to the URL is answered with 503 so the provider retries it, and the provider's own URL verification fails.
signing_secret_rotation_idstring
Identifies the latest signing-secret rotation; it increases by one each time a rotation starts. Zero when none has ever started. Pass this value to Confirm a signing secret rotation to confirm this specific rotation. A value naming a rotation that a newer one has since replaced is refused rather than confirming the wrong rotation.
urlstring
The URL to paste into the provider's app configuration as the event destination. It is built on your environment's domain, using its custom domain when one is set, and ends in a random token unique to this connection, so treat it as confidential. Returned whether or not a signing secret has been set. The URL accepts request bodies up to 1 MB and answers a larger one with 413. Until a signing secret is set it answers events with 503, so the provider retries them; an event that fails signature verification is answered with 400.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request, nothing created - connection_id is not a valid connection ID; the connection's provider publishes no webhook trigger, so it has no use for a webhook URL (error_code TRIGGER_INGRESS_NOT_APPLICABLE); or the provider's webhook trigger definitions are temporarily unavailable (error_code TRIGGER_INGRESS_DEFINITIONS_UNAVAILABLE)
404Not found - the connection does not exist in this environment, or Triggers isn't turned on for your environment
500Internal error - the webhook URL could not be created or read back; retry the request