Webhooks

Tilta webhooks deliver real-time event notifications to your backend as HTTP POST requests whenever something meaningful happens – a credit facility is approved, an order is confirmed, or an invoice becomes due. Instead of polling the API, you register an endpoint and Tilta pushes updates to you automatically, keeping your platform in sync without unnecessary API calls.

How webhooks work

When a subscribed event occurs, Tilta sends an HTTP POST request to your registered endpoint with a JSON body describing the event. Your endpoint must respond with an HTTP 2xx status code within a reasonable timeout to acknowledge receipt. If it does not, Tilta will retry the delivery automatically.

Event object structure

Every webhook payload follows the same envelope structure regardless of event type:

{
  "id": "14da1660-f340-485f-afd0-7c942501d302",
  "occurred_at": 1701862836,
  "type": "ORDER.CONFIRMED",
  "data": {
    "external_id": "order1",
    "status": "CONFIRMED"
  }
}

string

required

A UUID uniquely identifying this event delivery. Use this field to implement idempotency – log processed IDs and skip any event you have already handled.

integer

required

Unix timestamp (seconds) of when the event occurred on Tilta’s side. Use this alongside the resource ID to determine the most recent state when events arrive out of order.

string

required

The dot-separated event type in RESOURCE.PROCESS.OUTCOME format – for example, FACILITY.CREATION.ACCEPTED or ORDER.CONFIRMED. See the Event Reference for all available types.

object

required

Event-specific payload. The fields present depend on the event type. Refer to the Event Reference for the exact shape of each event’s data.

Event subscriptions

Tilta uses a hierarchical dot-separated naming convention – RESOURCE.PROCESS.OUTCOME – which allows you to subscribe at any level of specificity. A subscription to a prefix automatically receives all descendant events.

Subscription	Events received
`FACILITY.CREATION.ACCEPTED`	Only that exact event
`FACILITY.CREATION`	`FACILITY.CREATION.IN_REVIEW`, `FACILITY.CREATION.ACCEPTED`, `FACILITY.CREATION.REJECTED`
`FACILITY`	All `FACILITY.*` events
`ORDER`	All `ORDER.*` events

Subscribe only to the events your integration actually needs. Broad prefix subscriptions are convenient but increase the volume of webhook traffic your endpoint must handle.

Setting up a webhook endpoint

Build and deploy your endpoint

Create an HTTPS endpoint on your server that accepts POST requests and returns a 2xx HTTP status code promptly. Perform any heavy processing asynchronously after acknowledging receipt – do not block the response while you process the event.

// Example Express.js endpoint
app.post('/webhooks/tilta', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['tilta-signature'] as string;
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.TILTA_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  // Queue for async processing – respond immediately
  eventQueue.push(event);

  res.status(200).send('OK');
});

Call POST /v1/webhooks to subscribe your endpoint to one or more event types. The type field accepts either a full event type or a prefix.

curl -X POST https://api.tilta.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourplatform.com/webhooks/tilta",
    "type": "FACILITY.CREATION"
  }'

Tilta returns a subscription object that includes your signing secret. Store this secret securely – you will use it to verify incoming webhook signatures.

Implement signature verification

Every webhook request includes a Tilta-Signature header. Verify this signature before processing any event to ensure the request genuinely came from Tilta. See Signature Verification below for the full implementation.

Test with the sandbox

Use the sandbox base URL (https://api.tilta-sandbox.io) to register test endpoints and trigger events without affecting production data. Verify that your endpoint correctly receives, validates, and processes events before going live.

Signature verification

Tilta signs every webhook request so you can confirm it originated from Tilta and has not been tampered with. The signature is included in the Tilta-Signature HTTP header.

Signature header format

Tilta-Signature: t=1701862836,v1=f371bc4a311f2b009eef952dd83ca80e2b60026c8e935592d0f9c308453c813e

The header contains two comma-separated fields:

t – Unix timestamp (seconds) of when Tilta signed the request
v1 – HMAC-SHA256 hex digest of {webhookPayload}.{webhookTimestamp}, signed with your webhook signing secret

How to verify

To verify a signature, reconstruct the expected HMAC using the raw request body, the timestamp from the header, and your signing secret. Compare the result to the v1 value in the header using a timing-safe comparison to prevent timing attacks.

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t='))?.slice(2);
  const receivedSig = parts.find(p => p.startsWith('v1='))?.slice(3);

  if (!timestamp || !receivedSig) return false;

  // Reject events older than 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${payload}.${timestamp}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSig)
  );
}

Always reject webhook requests where the timestamp (t) is more than 5 minutes old. Tilta includes this timestamp so you can protect against replay attacks – where a legitimate captured request is resent maliciously. If you skip this check, an attacker could replay a valid past event to trigger duplicate processing on your platform.

Rotating signing keys

Rotate your webhook signing secret periodically to limit the blast radius of a potential secret leak. Call the rotate endpoint and update your application configuration with the new secret before the old one expires.

curl -X POST https://api.tilta.io/v1/webhooks/{type}/signature_key \
  -H "Authorization: Bearer YOUR_API_KEY"

Retry behavior

If your endpoint does not return a 2xx response – whether due to a server error, timeout, or any other failure – Tilta automatically retries the delivery. Retries continue for up to 12 hours using exponential backoff, giving your platform time to recover from transient outages without losing events.

Because retries can result in the same event being delivered more than once, always implement idempotency in your event handler. Log each processed event id and skip any event whose id you have already seen.

Managing subscriptions

List your subscriptions

curl https://api.tilta.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace a subscription

Use PUT /v1/webhooks/{type} to update the endpoint URL or configuration for an existing subscription.

curl -X PUT https://api.tilta.io/v1/webhooks/FACILITY.CREATION \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourplatform.com/webhooks/tilta-v2"
  }'

Unsubscribe

curl -X DELETE https://api.tilta.io/v1/webhooks/FACILITY.CREATION/unsubscribe \
  -H "Authorization: Bearer YOUR_API_KEY"

Best practices

Implement idempotent event handling

The same event can be delivered more than once due to retries. Before processing any event, check whether you have already handled an event with the same id. Store processed event IDs in a durable store (database, Redis, etc.) and skip duplicates. This prevents double-charging, duplicate fulfillment, or other unintended side effects.

Do not assume event ordering

Tilta does not guarantee that events arrive in chronological order. Network conditions and retry timing can cause earlier events to arrive after later ones. Always use the occurred_at timestamp combined with the resource’s external ID to determine the current state of a resource – do not rely solely on arrival order.

Respond quickly; process asynchronously

Your endpoint should acknowledge receipt by returning 200 OK as fast as possible. Push the event onto a queue and process it in a background worker. If your handler performs slow database writes or downstream API calls synchronously, it risks timing out and causing Tilta to retry an event you have already received.

Rotate signing keys periodically

Treat your webhook signing secret like a password. Rotate it on a regular schedule using POST /v1/webhooks/{type}/signature_key. Update your deployed secret before discarding the old one to avoid a gap in verification. Store secrets in environment variables or a secrets manager – never hardcode them in source code.

API reference

Method	Endpoint	Description
`POST`	`/v1/webhooks`	Subscribe to a webhook event or prefix
`GET`	`/v1/webhooks`	List all active subscriptions
`PUT`	`/v1/webhooks/{type}`	Replace an existing subscription
`DELETE`	`/v1/webhooks/{type}/unsubscribe`	Unsubscribe from an event type
`POST`	`/v1/webhooks/{type}/signature_key`	Rotate the signing secret for a subscription

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

How webhooks work

Event object structure

Event subscriptions

Setting up a webhook endpoint

Signature verification

Signature header format

How to verify

Rotating signing keys

Retry behavior

Managing subscriptions

List your subscriptions

Replace a subscription

Unsubscribe

Best practices

API reference

​How webhooks work

​Event object structure

​Event subscriptions

​Setting up a webhook endpoint

​Signature verification

​Signature header format

​How to verify

​Rotating signing keys

​Retry behavior

​Managing subscriptions

​List your subscriptions

​Replace a subscription

​Unsubscribe

​Best practices

​API reference

How webhooks work

Event object structure

Event subscriptions

Setting up a webhook endpoint

Signature verification

Signature header format

How to verify

Rotating signing keys

Retry behavior

Managing subscriptions

List your subscriptions

Replace a subscription

Unsubscribe

Best practices

API reference