SCscalekit
Triggers

Set a connection's webhook signing secret

Changed on

Stores the secret the provider signs its webhook events with, so events sent to the connection's webhook URL can be verified. Use this endpoint after CreateTriggerIngressEndpoint, with the signing secret copied from the provider's app configuration, and again whenever the provider's secret changes. Pass the connection ID in the path and signing_secret in the body; leading and trailing whitespace is removed before the secret is stored. A provider that sends no signature of its own takes a Scalekit-generated secret from GenerateTriggerSigningSecret instead, and is refused here. Until a secret is set, the webhook URL asks the provider to retry every event instead of accepting it. When a secret is already stored, setting a different one starts a rotation: both secrets are accepted until you confirm the rotation with ConfirmTriggerSigningSecretRotation, or for at most 24 hours. Sending the secret that is already stored changes nothing. Returns the endpoint with its masked secret and rotation state, including the signing_secret_rotation_id to confirm; the secret itself is never returned.

put/api/v1/connections/{connection_id}/trigger-ingress/signing-secret

Request

Path parameters

connection_idstring required

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

Request body

signing_secretstring required

The secret the provider signs its events with, copied from the provider's app configuration. For Slack this is the Signing Secret under Basic Information, not an API token. Between 8 and 4096 characters. For Gong, the RSA public key shown by 'Show public key'. Never returned by any endpoint and never written to a log.

Response

The secret is stored; the endpoint's masked secret and rotation state, including whether a rotation is now in progress

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. Present only when one 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 date-time

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 int64

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 ConfirmTriggerSigningSecretRotation 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.

Example response

{
  "connection_id": "conn_28128748834787840",
  "id": "tie_28128748834787840",
  "masked_signing_secret": "************************a4f9",
  "signing_secret_configured": true,
  "url": "https://acme.scalekit.dev/triggers/v1/kq3T9vX2bL8mN4pR7sW1yZ"
}

Changes