# 📡 Webhook Events Reference

Complete guide to all supported Tillhub webhook events

This document provides a comprehensive reference for all webhook events supported by Tillhub. Each event includes detailed descriptions, trigger conditions, and example payloads to help you implement robust webhook handling.

# Event Overview

Tillhub currently supports 8 webhook events across 5 main categories:

Category	Events	Description
💰 Transactions	1 event	Sales transactions and payments
👥 Customers	3 events	Customer lifecycle management
📦 Products	2 events	Product catalog changes
📈 Stock	1 event	Inventory tracking
💳 Balances	1 event	Account balance updates

# Event Naming Convention

All events follow the pattern: {entity}.{action}.v{version}

Examples:

transaction.create.v0 - New transaction created
customers.update.v0 - Customer information updated
products.delete.v0 - Product removed from catalog

# Transaction Events

# `transaction.create.v0`

🔔 Triggered when: A new transaction is successfully created in the system

📋 Use cases:

Real-time sales reporting
Inventory synchronization
Customer loyalty point calculation
Accounting system integration

📊 Example Payload:

{
  "webhook_id": "ff30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "c6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "transaction",
  "event_type": "create",
  "event_version": 0,
  "entity_instance_id": "10b06f38-031d-4e0c-8706-0474c8c5b61c",
  "timestamp": "2022-12-13T08:45:00.881Z",
  "payload": {
    "id": "10b06f38-031d-4e0c-8706-0474c8c5b61c",
    "register_id": "reg_12345",
    "branch_id": "branch_67890",
    "staff_id": "staff_abc123",
    "customer_id": "customer_def456",
    "status": "completed",
    "total_amount": 150.75,
    "tax_amount": 19.25,
    "currency": "EUR",
    "payment_method": "card",
    "created_at": "2022-12-13T08:45:00.881Z",
    "items": [
      {
        "product_id": "product_789",
        "sku": "ITEM-001",
        "name": "Premium Coffee Beans",
        "quantity": 2,
        "unit_price": 65.50,
        "total_price": 131.00,
        "tax_rate": 0.19
      },
      {
        "product_id": "product_790",
        "sku": "ITEM-002", 
        "name": "Ceramic Mug",
        "quantity": 1,
        "unit_price": 19.75,
        "total_price": 19.75,
        "tax_rate": 0.19
      }
    ],
    "discounts": [
      {
        "type": "percentage",
        "value": 10,
        "amount": 15.08,
        "reason": "Customer loyalty discount"
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

📖 Documentation:

# Customer Events

# `customers.create.v0`

🔔 Triggered when: A new customer account is created

📋 Use cases:

Welcome email campaigns
CRM system synchronization
Customer analytics tracking
Loyalty program enrollment

📊 Example Payload:

{
  "webhook_id": "aa30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "bb6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "customers",
  "event_type": "create",
  "event_version": 0,
  "entity_instance_id": "customer_def456",
  "timestamp": "2022-12-13T09:15:30.245Z",
  "payload": {
    "id": "customer_def456",
    "customer_number": "CUST-2022-001234",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+49 30 12345678",
    "date_of_birth": "1985-03-15",
    "addresses": [
      {
        "type": "billing",
        "street": "Hauptstraße 123",
        "city": "Berlin",
        "postal_code": "10115",
        "country": "DE"
      }
    ],
    "preferences": {
      "newsletter": true,
      "sms_notifications": false,
      "language": "de"
    },
    "created_at": "2022-12-13T09:15:30.245Z"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

📖 Documentation:

# `customers.update.v0`

🔔 Triggered when: Existing customer information is modified

📋 Use cases:

Profile synchronization
Address book updates
Preference changes tracking
Data consistency maintenance

📊 Example Payload:

{
  "webhook_id": "cc30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "dd6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "customers",
  "event_type": "update",
  "event_version": 0,
  "entity_instance_id": "customer_def456",
  "timestamp": "2022-12-13T14:22:15.678Z",
  "payload": {
    "id": "customer_def456",
    "customer_number": "CUST-2022-001234",
    "email": "john.doe.new@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+49 30 87654321",
    "addresses": [
      {
        "type": "billing",
        "street": "Neue Straße 456",
        "city": "Munich",
        "postal_code": "80331",
        "country": "DE"
      }
    ],
    "preferences": {
      "newsletter": true,
      "sms_notifications": true,
      "language": "en"
    },
    "updated_at": "2022-12-13T14:22:15.678Z",
    "changes": [
      {
        "field": "email",
        "old_value": "john.doe@example.com",
        "new_value": "john.doe.new@example.com"
      },
      {
        "field": "phone",
        "old_value": "+49 30 12345678",
        "new_value": "+49 30 87654321"
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

📖 Documentation:

# `customers.delete.v0`

🔔 Triggered when: A customer account is permanently deleted

📋 Use cases:

GDPR compliance processing
Data cleanup workflows
CRM synchronization
Analytics data adjustment

📊 Example Payload:

{
  "webhook_id": "ee30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "ff6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "customers",
  "event_type": "delete",
  "event_version": 0,
  "entity_instance_id": "customer_def456",
  "timestamp": "2022-12-13T16:45:22.891Z",
  "payload": {
    "id": "customer_def456",
    "customer_number": "CUST-2022-001234",
    "deleted_at": "2022-12-13T16:45:22.891Z",
    "deletion_reason": "Customer requested account deletion",
    "metadata": {
      "total_transactions": 15,
      "total_spent": 1250.75,
      "last_purchase": "2022-11-28T10:30:00.000Z",
      "account_created": "2022-01-15T09:15:30.245Z"
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

📖 Documentation:

# Product Events

# `products.create.v0`

🔔 Triggered when: A new product is added to the catalog

📋 Use cases:

Inventory system synchronization
E-commerce catalog updates
Price monitoring setup
Search index updates

📊 Example Payload:

{
  "webhook_id": "gg30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "hh6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "products",
  "event_type": "create",
  "event_version": 0,
  "entity_instance_id": "product_789",
  "timestamp": "2022-12-13T11:30:45.123Z",
  "payload": {
    "id": "product_789",
    "sku": "COFFEE-PREMIUM-001",
    "name": "Premium Arabica Coffee Beans",
    "description": "Single-origin premium coffee beans from Ethiopian highlands",
    "category": "Beverages",
    "subcategory": "Coffee",
    "brand": "Highland Roasters",
    "barcode": "1234567890123",
    "prices": [
      {
        "type": "retail",
        "amount": 65.50,
        "currency": "EUR",
        "tax_rate": 0.19
      },
      {
        "type": "wholesale",
        "amount": 45.85,
        "currency": "EUR",
        "tax_rate": 0.19
      }
    ],
    "stock": {
      "quantity": 150,
      "unit": "kg",
      "minimum_stock": 20,
      "location": "Warehouse A"
    },
    "attributes": {
      "weight": "1000g",
      "origin": "Ethiopia",
      "roast_level": "Medium",
      "organic": true
    },
    "active": true,
    "created_at": "2022-12-13T11:30:45.123Z"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

📖 Documentation:

# `products.update.v0`

🔔 Triggered when: Product information is modified

📋 Use cases:

Price change notifications
Inventory level updates
Catalog synchronization
Product availability alerts

📊 Example Payload:

{
  "webhook_id": "ii30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "jj6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "products",
  "event_type": "update",
  "event_version": 0,
  "entity_instance_id": "product_789",
  "timestamp": "2022-12-13T15:20:18.456Z",
  "payload": {
    "id": "product_789",
    "sku": "COFFEE-PREMIUM-001",
    "name": "Premium Arabica Coffee Beans",
    "description": "Single-origin premium coffee beans from Ethiopian highlands - Now Fair Trade Certified!",
    "prices": [
      {
        "type": "retail",
        "amount": 69.99,
        "currency": "EUR",
        "tax_rate": 0.19
      }
    ],
    "stock": {
      "quantity": 75,
      "unit": "kg",
      "minimum_stock": 20,
      "location": "Warehouse A"
    },
    "attributes": {
      "weight": "1000g",
      "origin": "Ethiopia",
      "roast_level": "Medium",
      "organic": true,
      "fair_trade": true
    },
    "updated_at": "2022-12-13T15:20:18.456Z",
    "changes": [
      {
        "field": "prices.retail.amount",
        "old_value": 65.50,
        "new_value": 69.99
      },
      {
        "field": "stock.quantity",
        "old_value": 150,
        "new_value": 75
      },
      {
        "field": "attributes.fair_trade",
        "old_value": null,
        "new_value": true
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

📖 Documentation:

# Stock Events

# `stocks-book.create.v0`

🔔 Triggered when: A new stock movement is recorded

📋 Use cases:

Real-time inventory tracking
Stock level alerts
Reorder point notifications
Inventory audit trails

📊 Example Payload:

{
  "webhook_id": "kk30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "ll6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "stocks-book",
  "event_type": "create",
  "event_version": 0,
  "entity_instance_id": "stock_movement_123",
  "timestamp": "2022-12-13T13:45:12.789Z",
  "payload": {
    "id": "stock_movement_123",
    "product_id": "product_789",
    "sku": "COFFEE-PREMIUM-001",
    "movement_type": "sale",
    "quantity_change": -2,
    "quantity_before": 152,
    "quantity_after": 150,
    "unit": "kg",
    "location": "Warehouse A",
    "reference": {
      "type": "transaction",
      "id": "10b06f38-031d-4e0c-8706-0474c8c5b61c"
    },
    "cost_per_unit": 32.75,
    "total_cost": 65.50,
    "currency": "EUR",
    "notes": "Sold via POS transaction",
    "created_at": "2022-12-13T13:45:12.789Z",
    "staff_id": "staff_abc123"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

📖 Documentation:

# Balance Events

# `balances.create.v0`

🔔 Triggered when: A new balance entry is created (cash register, account balance, etc.)

📋 Use cases:

Cash register reconciliation
Financial reporting
Audit trail maintenance
Daily balance tracking

📊 Example Payload:

{
  "webhook_id": "mm30cfdf-5167-4f72-b4fc-c1d72db3c07e",
  "event_id": "nn6fe918a-7bdc-4ccd-af36-95c03853233d",
  "event_entity": "balances",
  "event_type": "create",
  "event_version": 0,
  "entity_instance_id": "balance_456",
  "timestamp": "2022-12-13T18:00:00.000Z",
  "payload": {
    "id": "balance_456",
    "register_id": "reg_12345",
    "branch_id": "branch_67890",
    "balance_type": "end_of_day",
    "currency": "EUR",
    "cash_amount": 1247.85,
    "card_amount": 3456.70,
    "total_amount": 4704.55,
    "expected_amount": 4698.20,
    "variance": 6.35,
    "transaction_count": 87,
    "period": {
      "start": "2022-12-13T08:00:00.000Z",
      "end": "2022-12-13T18:00:00.000Z"
    },
    "staff_id": "staff_abc123",
    "notes": "End of day balance - minor variance due to cash rounding",
    "created_at": "2022-12-13T18:00:00.000Z"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

📖 Documentation:

# Event Structure

All Tillhub webhook events follow a consistent structure:

# Common Fields

Field	Type	Description
`webhook_id`	`string`	Unique identifier for the webhook configuration
`event_id`	`string`	Unique identifier for this specific event
`event_entity`	`string`	The entity type (e.g., "transaction", "customers")
`event_type`	`string`	The action type (e.g., "create", "update", "delete")
`event_version`	`number`	Event schema version (currently 0 for all events)
`entity_instance_id`	`string`	Unique identifier of the affected entity instance
`timestamp`	`string`	ISO 8601 timestamp when the event occurred
`payload`	`object`	Entity-specific data (varies by event type)

# Event Identification

Event Name Format: {entity}.{action}.v{version}

Examples:

transaction.create.v0
customers.update.v0
products.delete.v0

# Payload Variations

The payload field structure varies based on the event type:

Create events: Full entity data
Update events: Current state + changes array showing modifications
Delete events: Entity identifier + deletion metadata

# Additional Resources

# 🔗 Quick Links

Main Webhook Guide - Complete webhook implementation guide
API Documentation (opens new window) - Full Tillhub API reference
JSON Schemas (opens new window) - Payload validation schemas

# 💡 Best Practices

Event Filtering - Subscribe only to events you need
Idempotency - Handle duplicate events gracefully
Error Handling - Implement robust error recovery
Payload Validation - Validate incoming payloads against schemas
Async Processing - Process events asynchronously for better performance

💬 Need Help?

If you have questions about specific events or need help implementing webhook handling, check our main webhook guide or contact our support team.

Happy Webhooking! 🎉

# 📡 Webhook Events Reference

# 📋 Table of Contents

# Event Overview

# Event Naming Convention

# Transaction Events

# transaction.create.v0

# Customer Events

# customers.create.v0

# customers.update.v0

# customers.delete.v0

# Product Events

# products.create.v0

# products.update.v0

# Stock Events

# stocks-book.create.v0

# Balance Events

# balances.create.v0

# Event Structure

# Common Fields

# Event Identification

# Payload Variations

# Additional Resources

# 🔗 Quick Links

# 💡 Best Practices

# `transaction.create.v0`

# `customers.create.v0`

# `customers.update.v0`

# `customers.delete.v0`

# `products.create.v0`

# `products.update.v0`

# `stocks-book.create.v0`

# `balances.create.v0`