Inbound Webhooks

Inbound webhooks allow external systems to push data into Total Access. Each inbound webhook has a unique URL and authentication mechanism.

How it works

You create an inbound webhook in Total Access
Total Access generates a unique URL and API key (or signing secret)
You share the URL and credentials with the external system
The external system sends HTTP POST requests to the webhook URL
Total Access authenticates, validates, and processes the data
The result is logged in webhook logs

Configuration

Creating an inbound webhook

Navigate to Total Integration → Inbound Webhooks (or use the Developer Portal)
Click Create Inbound Webhook
Enter a name and select the webhook type
Choose an authentication method (API Key or HMAC recommended)
Save — the webhook URL and credentials are generated

Webhook URL format

https://totalaccess.co.za/api/v1/webhooks/inbound/{webhook_uuid}

The UUID is generated automatically and is unique per webhook.

Webhook types

Type	Description	Typical Payload
`fleet_webview`	Receive dashboard URLs from fleet providers	`{ vehicle_id, dashboard_url, expiry }`
`vehicle_location`	Receive GPS location updates	`{ device_id, lat, lon, speed_kmh, ignition }`
`payment_notification`	Receive payment confirmations	`{ transaction_id, amount, currency, status, reference }`
`data_sync`	Generic data synchronization	`{ entity_type, entity_id, action, data }`
`notification`	Receive notifications from external systems	`{ type, title, message, priority }`
`whatsapp_message`	Receive WhatsApp message events	`{ event, waId, senderName, text, type, timestamp }`
`supplier_invoice`	Receive supplier invoice data	`{ invoice_number, vendor_name, line_items, grand_total, currency }`
`custom`	Custom payload format	Any JSON structure

Authentication methods

Method	Header	Recommended
API Key	`X-API-Key: ta_wh_...`	Yes
HMAC Signature	`X-TotalAccess-Signature: sha256=...`	Yes
None	—	No

When API Key auth is selected, an API key with the ta_wh_ prefix is auto-generated specifically for this webhook. This is separate from the standard ta_sk_ API keys used for the REST API.

Sending data

With API Key authentication

curl -X POST https://totalaccess.co.za/api/v1/webhooks/inbound/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: ta_wh_prod_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": "VH-001",
    "dashboard_url": "https://fleet-provider.com/live/vh001",
    "expiry": "2026-01-03T00:00:00Z"
  }'

With HMAC authentication

import crypto from 'crypto';

const webhookUrl = 'https://totalaccess.co.za/api/v1/webhooks/inbound/UUID';
const signingSecret = 'your_signing_secret';

const payload = {
  vehicle_id: 'VH-001',
  dashboard_url: 'https://fleet-provider.com/live/vh001',
  expiry: '2026-01-03T00:00:00Z'
};

const body = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', signingSecret)
  .update(body)
  .digest('hex');

const response = await fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-TotalAccess-Signature': `sha256=${signature}`
  },
  body
});

const result = await response.json();
console.log(result);

import hmac
import hashlib
import requests

webhook_url = 'https://totalaccess.co.za/api/v1/webhooks/inbound/UUID'
signing_secret = 'your_signing_secret'

payload = {
    'vehicle_id': 'VH-001',
    'dashboard_url': 'https://fleet-provider.com/live/vh001',
    'expiry': '2026-01-03T00:00:00Z'
}

body = json.dumps(payload)
signature = hmac.new(
    signing_secret.encode('utf-8'),
    body.encode('utf-8'),
    hashlib.sha256
).hexdigest()

response = requests.post(
    webhook_url,
    headers={
        'Content-Type': 'application/json',
        'X-TotalAccess-Signature': f'sha256={signature}'
    },
    data=body
)

print(response.json())

Response

{
  "success": true,
  "data": {
    "id": "rec_xyz789",
    "status": "processed",
    "message": "Data received and processed"
  }
}

Error responses

HTTP Status	Error Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key / signature
403	`FORBIDDEN`	Webhook is inactive or deleted
404	`NOT_FOUND`	Webhook UUID not found
422	`VALIDATION_ERROR`	Invalid payload format

Webhook credentials

After creating an inbound webhook, the credentials are displayed once:

Webhook URL — The unique URL for sending data
API Key (if api_key auth) — The ta_wh_ prefixed key
Signing Secret (if hmac auth) — The HMAC secret

Credentials are only shown once at creation time. Store them securely. If lost, you will need to create a new webhook.

Monitoring

All inbound webhook receipts are logged in Webhook Logs. See Webhook Logs for the logs API.

Inbound Webhooks

On this page