> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a subscription
> Subscribe to a Tilta webhook event type and receive real-time HTTP POST notifications at your endpoint whenever the specified event fires.
Webhook subscriptions tell Tilta where to send event notifications. When you create a subscription, you provide an event type – either a specific event or a parent prefix such as `FACILITY` – and a `destination_url`. Tilta delivers an HTTP POST request to that URL whenever a matching event occurs. The response includes a `signature_key` that you must store securely: it is shown only once and cannot be retrieved again.
The `signature_key` is only visible in this creation response. Tilta does not store or re-expose it. If you lose it, [rotate
the key](/api-reference/webhooks/rotate-signature-key) to get a new one.
## Verifying webhook signatures
Every webhook request Tilta sends includes an `X-Tilta-Signature` header. Compute an HMAC-SHA256 digest of the raw request body using your `signature_key` and compare it to the header value to confirm the request is genuine.
```python theme={null}
import hmac
import hashlib
def verify_signature(payload_bytes: bytes, header: str, secret: str) -> bool:
expected = hmac.new(
secret.encode("utf-8"),
payload_bytes,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, header)
```
Subscribe to parent prefixes (e.g. `FACILITY`, `ORDER`) during development so you can inspect all event shapes in one place.
Switch to specific leaf-event subscriptions in production to reduce noise and tighten access control.
## OpenAPI
````yaml POST /v1/webhooks
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/webhooks:
post:
tags:
- Webhooks
summary: Create webhook subscription
description: |
Subscribes to a Webhook.
This will allow you to receive updates from us on the provided url.
requestBody:
content:
application/json:
schema:
type: object
properties:
destination_url:
type: string
format: uri
description: >-
Where the webhook should be sent to. This must be an
endpoint that handles POST requests.
type:
type: string
enum:
- 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
description: >-
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`.
example: FACILITY.CREATION.ACCEPTED
required:
- destination_url
- type
additionalProperties: false
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
destination_url:
type: string
format: uri
description: >-
Where the webhook should be sent to. This must be an
endpoint that handles POST requests.
type:
type: string
enum:
- 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
description: >-
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`.
example: FACILITY.CREATION.ACCEPTED
signature_key:
type: string
created_at:
type: number
description: >-
Timestamp indicating when the webhook was created (unix
time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the webhook was updated
(unix time in seconds).
example: 1582896122
required:
- destination_url
- type
- signature_key
- created_at
- updated_at
additionalProperties: false
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/webhookConflictSchema'
security:
- bearerAuth: []
components:
schemas:
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
webhookConflictSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Webhook with the same type already exists
code:
type: string
description: Error code.
example: CONFLICT
required:
- error
- code
description: Webhook with the same type already exists
example:
error: Webhook with the same type already exists
code: CONFLICT
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````