Inbound Webhooks

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

List inbound webhooks

curl -X GET https://totalaccess.co.za/api/v1/integrations/inbound-webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Fleet Dashboard Provider",
      "description": "Receive dashboard URLs from fleet provider",
      "webhook_type": "fleet_webview",
      "auth_method": "api_key",
      "is_active": true,
      "receive_count": 5400,
      "last_received_at": "2026-07-22T14:00:00Z",
      "created_by": 15,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-07-22T14:00:00Z"
    }
  ],
  "available_types": ["fleet_webview", "vehicle_location", "payment_notification", "data_sync", "notification", "whatsapp_message", "supplier_invoice", "custom"],
  "available_auth_methods": ["api_key", "hmac", "none"],
  "can_view_all_users": false
}

Create inbound webhook

curl -X POST https://totalaccess.co.za/api/v1/integrations/inbound-webhooks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fleet Dashboard Provider",
    "webhook_type": "fleet_webview",
    "auth_method": "api_key",
    "description": "Receive dashboard URLs from fleet provider",
    "is_active": true
  }'

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Fleet Dashboard Provider",
    "description": "Receive dashboard URLs from fleet provider",
    "webhook_type": "fleet_webview",
    "auth_method": "api_key",
    "is_active": true,
    "receive_count": 0,
    "created_at": "2026-07-22T15:00:00Z",
    "updated_at": "2026-07-22T15:00:00Z"
  },
  "api_key": "ta_wh_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6..."
}

The full api_key is only returned once at creation time. Store it securely. For hmac auth method, a secret_key is returned instead.

Webhook types

Type	Description	Typical Use
`fleet_webview`	Receive dashboard URLs from fleet providers	Fleet management integration
`vehicle_location`	Receive GPS location updates	Real-time vehicle tracking
`payment_notification`	Receive payment confirmations	Payment gateway integration
`data_sync`	Generic data synchronization	Custom integrations
`notification`	Receive notifications from external systems	Alert forwarding
`whatsapp_message`	Receive WhatsApp message events	WhatsApp integration
`supplier_invoice`	Receive supplier invoice data	Accounts payable automation
`custom`	Custom payload format	Flexible integration

Authentication methods

Method	Header	Description
`api_key`	`X-API-Key: ta_wh_...`	External system sends the webhook API key (recommended)
`hmac`	`X-TotalAccess-Signature: sha256=...`	HMAC-SHA256 signature validation (recommended)
`none`	—	No authentication (use with caution)

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

Update inbound webhook

curl -X PATCH https://totalaccess.co.za/api/v1/integrations/inbound-webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "is_active": false,
    "description": "Updated description"
  }'

Get inbound webhook details

curl -X GET https://totalaccess.co.za/api/v1/integrations/inbound-webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete inbound webhook

curl -X DELETE https://totalaccess.co.za/api/v1/integrations/inbound-webhooks/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Deletion is a soft delete — the webhook URL becomes inactive but the record is retained.

Sending data to an inbound webhook

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"
  }'

HMAC authentication

For HMAC-authenticated webhooks, the external system must sign the raw request body:

import crypto from 'crypto';

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

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

Response

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

Inbound Webhooks

On this page