Webhooks

Webhooks allow your application to receive real-time notifications when events occur in Tiketti.

Overview

When an event occurs (e.g., ticket created, message received), Tiketti sends an HTTP POST request to your configured endpoint with event data.

Webhook Endpoints

Method	Endpoint	Description
GET	`/webhooks`	List webhooks
POST	`/webhooks`	Create webhook
GET	`/webhooks/:id`	Get webhook
PATCH	`/webhooks/:id`	Update webhook
DELETE	`/webhooks/:id`	Delete webhook

Create Webhook

POST /api/v1/webhooks

{
  "url": "https://your-server.com/webhooks/tiketti",
  "events": ["ticket.created", "ticket.updated", "message.created"],
  "secret": "your_webhook_secret"
}

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to receive events
`events`	string[]	Yes	Events to subscribe to
`secret`	string	No	Secret for signature verification
`active`	boolean	No	Enable/disable webhook

Available Events

Ticket Events

Event	Trigger
`ticket.created`	New ticket created
`ticket.updated`	Ticket properties changed
`ticket.deleted`	Ticket deleted
`ticket.assigned`	Ticket assigned to user
`ticket.status_changed`	Status changed

Message Events

Event	Trigger
`message.created`	New message on ticket
`message.deleted`	Message deleted

Contact Events

Event	Trigger
`contact.created`	New contact created
`contact.updated`	Contact updated
`contact.deleted`	Contact deleted

Time Entry Events

Event	Trigger
`time_entry.created`	Time logged
`time_entry.updated`	Time entry updated
`time_entry.deleted`	Time entry deleted

Webhook Payload

Headers

Header	Description
`Content-Type`	`application/json`
`X-Tiketti-Event`	Event type
`X-Tiketti-Delivery`	Unique delivery ID
`X-Tiketti-Signature`	HMAC signature
`X-Tiketti-Timestamp`	Event timestamp

Body Structure

{
  "event": "ticket.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "id": "ticket-uuid",
    "code": "ACME-42",
    "subject": "Cannot login",
    "status": "open",
    "priority": "high",
    "contact": {
      "id": "contact-uuid",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Signature Verification

Verify webhook authenticity using the signature:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Retry Policy

Failed webhook deliveries are retried:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is marked as failed. Fix the issue and re-enable.

Best Practices

Endpoint Requirements

Use HTTPS (required)
Respond with 2xx within 30 seconds
Return quickly, process asynchronously
Handle duplicate deliveries (idempotency)

Security

Use a strong secret
Verify signatures
Validate event types
Use IP allowlisting if possible

Reliability

Respond immediately, process later
Use a queue for processing
Handle retries gracefully
Log all webhook deliveries

Testing

Test Endpoint

Send a test event to your webhook:

POST /api/v1/webhooks/:id/test

Sends a test.ping event to verify connectivity.

Webhook Logs

View delivery attempts:

GET /api/v1/webhooks/:id/deliveries

{
  "data": [
    {
      "id": "delivery-uuid",
      "event": "ticket.created",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 150,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Error Codes

Code	Description
`WEBHOOK_NOT_FOUND`	Webhook doesn’t exist
`INVALID_URL`	URL must be HTTPS
`INVALID_EVENTS`	Unknown event types
`WEBHOOK_DISABLED`	Webhook is not active