Skip to main content
POST
Rotate webhook signature key
Every webhook subscription has a signature_key that Tilta uses to sign outgoing event payloads. Rotating this key invalidates the previous key and replaces it with a newly generated secret. The new signature_key is included in the response body exactly once – Tilta never stores or re-exposes it. You must update your webhook handler to use the new key immediately after rotation, otherwise signature verification will fail and you will reject legitimate events from Tilta.
The signature_key is returned only in this response. Once you close or discard it, it is gone permanently. Store it immediately in a secure secret manager such as AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or HashiCorp Vault. Never log this value or commit it to source control.

Zero-downtime rotation procedure

Follow these steps to rotate your signature key without dropping any valid webhook deliveries:
1

Initiate the rotation

Call this endpoint and capture the new signature_key from the response immediately.
2

Store the new key alongside the old key

Temporarily configure your webhook handler to accept signatures verified by either the old key or the new key. This prevents a gap where in-flight events signed with the old key are rejected.
3

Deploy the updated handler

Roll out the updated handler that accepts both keys. Confirm it is live and processing events correctly.
4

Remove the old key

After a brief observation window (typically 5–15 minutes to allow any in-flight deliveries to drain), remove the old key from your handler so that only the new key is accepted.
Schedule key rotations as part of your regular security hygiene cycle – for example, every 90 days or whenever a team member with access to the key departs. Automate the rotation using a secrets-management pipeline to avoid manual errors.

Authorizations

Authorization
string
header
required

Your Tilta API key, sent as Bearer <key>.

Path Parameters

type
enum<string>
required

The webhook's type. Supports the hierarchical dot-notation taxonomy; subscribing to a parent (e.g. FACILITY) implicitly subscribes to every descendant event (e.g. FACILITY.CREATION.ACCEPTED). Other valid values include ORDER.CONFIRMED and INVOICE.DUE.

Available options:
BUYER,
BUYER.CREATED,
BUYER.UPDATED,
FACILITY,
FACILITY.CREATION,
FACILITY.CREATION.ACCEPTED,
FACILITY.CREATION.IN_REVIEW,
FACILITY.CREATION.REJECTED,
FACILITY.EXPIRED,
FACILITY.FROZEN,
FACILITY.INCREASE,
FACILITY.INCREASE.ACCEPTED,
FACILITY.INCREASE.IN_REVIEW,
FACILITY.INCREASE.REJECTED,
FACILITY.RENEWAL,
FACILITY.RENEWAL.ACCEPTED,
FACILITY.RENEWAL.IN_REVIEW,
FACILITY.RENEWAL.REJECTED,
FACILITY.UNFROZEN,
INVOICE,
INVOICE.CLOSED,
INVOICE.CREATED,
INVOICE.DUE,
INVOICE.FILE,
INVOICE.FILE.CREATED,
INVOICE.FILE.DELETED,
INVOICE.FILE.REPLACED,
INVOICE.FINANCING,
INVOICE.FINANCING.PAID_OUT,
ORDER,
ORDER.CANCELLED,
ORDER.CLOSED,
ORDER.CONFIRMED,
ORDER.DISBURSED,
ORDER.EXPIRED
Example:

"FACILITY.CREATION.ACCEPTED"

Response

destination_url
string<uri>
required

Where the webhook should be sent to. This must be an endpoint that handles POST requests.

type
enum<string>
required

The webhook's type. Supports the hierarchical dot-notation taxonomy; subscribing to a parent (e.g. FACILITY) implicitly subscribes to every descendant event (e.g. FACILITY.CREATION.ACCEPTED). Other valid values include ORDER.CONFIRMED and INVOICE.DUE.

Available options:
BUYER,
BUYER.CREATED,
BUYER.UPDATED,
FACILITY,
FACILITY.CREATION,
FACILITY.CREATION.ACCEPTED,
FACILITY.CREATION.IN_REVIEW,
FACILITY.CREATION.REJECTED,
FACILITY.EXPIRED,
FACILITY.FROZEN,
FACILITY.INCREASE,
FACILITY.INCREASE.ACCEPTED,
FACILITY.INCREASE.IN_REVIEW,
FACILITY.INCREASE.REJECTED,
FACILITY.RENEWAL,
FACILITY.RENEWAL.ACCEPTED,
FACILITY.RENEWAL.IN_REVIEW,
FACILITY.RENEWAL.REJECTED,
FACILITY.UNFROZEN,
INVOICE,
INVOICE.CLOSED,
INVOICE.CREATED,
INVOICE.DUE,
INVOICE.FILE,
INVOICE.FILE.CREATED,
INVOICE.FILE.DELETED,
INVOICE.FILE.REPLACED,
INVOICE.FINANCING,
INVOICE.FINANCING.PAID_OUT,
ORDER,
ORDER.CANCELLED,
ORDER.CLOSED,
ORDER.CONFIRMED,
ORDER.DISBURSED,
ORDER.EXPIRED
Example:

"FACILITY.CREATION.ACCEPTED"

signature_key
string
required
created_at
number
required

Timestamp indicating when the webhook was created (unix time in seconds).

Example:

1582896122

updated_at
number
required

Timestamp indicating the last time the webhook was updated (unix time in seconds).

Example:

1582896122