Webhook Logs

All webhook activity is logged — outbound deliveries, inbound receipts, and API usage. Logs are queryable with filters and include full request/response details for debugging.

List webhook logs

curl -X GET "https://totalaccess.co.za/api/v1/integrations/webhook-logs?source=outbound&status=failed&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Query parameters

Parameter	Type	Description
`source`	string	Filter by source: `outbound`, `inbound`, `api`, `all` (default)
`status`	string	Filter by status: `success`, `failed`, `pending`, `retrying`
`event_type`	string	Filter by event type (e.g. `invoice.created`)
`webhook_id`	string	Filter by webhook ID
`start_date`	string	ISO 8601 start date
`end_date`	string	ISO 8601 end date
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50, max: 100)

Response:

{
  "success": true,
  "data": [
    {
      "id": "log_abc123",
      "source": "outbound",
      "event_type": "invoice.created",
      "webhook_id": "wh_abc123",
      "webhook_name": "Invoice Sync",
      "status": "failed",
      "request": {
        "method": "POST",
        "url": "https://your-app.com/webhooks/ta",
        "headers": {
          "Content-Type": "application/json",
          "X-TotalAccess-Signature": "sha256=..."
        },
        "body": { "event": "invoice.created", "data": { ... } }
      },
      "response": {
        "status_code": 500,
        "body": "Internal Server Error",
        "headers": { ... }
      },
      "attempt_number": 2,
      "error_message": "HTTP 500: Internal Server Error",
      "duration_ms": 1250,
      "created_at": "2026-07-22T14:05:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 234,
    "stats": {
      "total_deliveries": 12400,
      "successful": 12150,
      "failed": 180,
      "pending": 70,
      "success_rate": 98.0
    }
  }
}

Get log statistics

Statistics are included in the meta.stats field of list responses. For dedicated statistics:

curl -X GET "https://totalaccess.co.za/api/v1/integrations/webhook-logs?stats_only=true&start_date=2026-07-01T00:00:00Z&end_date=2026-07-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "success": true,
  "data": {
    "total_deliveries": 12400,
    "successful": 12150,
    "failed": 180,
    "pending": 70,
    "success_rate": 98.0,
    "by_source": {
      "outbound": { "total": 8000, "successful": 7900, "failed": 100 },
      "inbound": { "total": 3400, "successful": 3350, "failed": 50 },
      "api": { "total": 1000, "successful": 900, "failed": 30 }
    },
    "by_status": {
      "success": 12150,
      "failed": 180,
      "pending": 70,
      "retrying": 0
    }
  }
}

Log sources

Source	Description
`outbound`	Outbound webhook delivery attempts (from `work_item_webhook_deliveries`)
`inbound`	Inbound webhook receipts (from `webhook_logs`)
`api`	API usage logs (from `api_usage`)

Create a manual log entry

curl -X POST https://totalaccess.co.za/api/v1/integrations/webhook-logs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "inbound",
    "event_type": "custom",
    "webhook_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "success",
    "request_body": { "custom": "data" },
    "response_body": { "processed": true }
  }'

Delete logs

Delete logs older than a specified date or by filter:

curl -X DELETE "https://totalaccess.co.za/api/v1/integrations/webhook-logs?before_date=2026-06-01T00:00:00Z&source=outbound" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Log deletion is permanent. Consider exporting logs before deleting.

Debugging failed deliveries

Check the log entry — Look at response.status_code and error_message
Inspect the request — Verify the request.body matches the expected payload format
Check the signature — Ensure your endpoint is correctly verifying the HMAC signature
Review retry attempts — Each retry is logged as a separate entry with incrementing attempt_number
Test with the playground — Use the Webhook Test Playground to send test events

Webhook Logs

On this page