Webhooks

Webhooks let Manifold push notifications to your endpoint instead of you polling.

You register a URL, an HTTP verb, optional custom headers, the connections to watch, and the notification types you want.
Webhooks are the only objects you create, update, and delete through this API.
Base URL: https://api.analytics.autos
Authentication on these endpoints uses the X-API-KEY header.
These endpoints are account-level. They are not scoped by a Connection-Id header. You scope a webhook to connections in the request body instead.

Notification types

Manifold sends two types of notifications. One for events. One for accidents.

A single webhook can subscribe to either type or both. You set this with notificationTypes. At least one value is required.

Event notifications

Enum value: EventNotification (2).
A detected driving safety event. For example harsh braking or a collision.
Each event carries an Event Risk rating from 1 (very low) to 5 (critical).

Accident notifications

Enum value: Fnol (1). FNOL stands for first notice of loss.
The insurance-claim lifecycle for a detected accident.
Delivered at three notification levels:
- 1 First detection.
- 2 Verified.
- 3 Report-ready.
The same accident is delivered once per level. Use the event ID to tie the levels together.

Note: the notification type is delivered as an integer in the payload type field. 1 is an accident notification. 2 is an event notification.

Delivery envelope

Every delivery uses the same outer envelope. Manifold calls your URL with POST or PUT, based on the httpVerb you configured.

{
  "timestamp": "2026-06-17T14:32:05Z",
  "type": 2,
  "data": {}
}

timestamp is the UTC RFC 3339 time of the delivery.
type is the notification type integer. 1 accident, 2 event.
data is the payload for that notification type. See below.

Event notification payload (`type = 2`)

Payload fields for event notifications. The whole delivery is serialized as camelCase, including the data object.

eventId
issuedOn
translatedIncidentTypes
eventRisk (1 very low to 5 critical)
vehicleId
vehicleName
vehicleVin
vehicleGroups
recipients

Sample delivery:

{
  "timestamp": "2026-06-17T14:32:05Z",
  "type": 2,
  "data": {
    "eventId": "b71c4d92-2e88-4a13-9f0c-5d6e7a8b9c01",
    "issuedOn": "2026-06-17T14:31:40Z",
    "translatedIncidentTypes": ["Harsh Braking"],
    "eventRisk": 4,
    "vehicleId": "a18f6e22-9c3d-4b7a-8e15-0f2c4d6e8a90",
    "vehicleName": "Truck 14",
    "vehicleVin": "1HGCM82633A004352",
    "vehicleGroups": ["West Region"],
    "recipients": ["[email protected]"]
  }
}

eventRisk is the field to triage on. Route 4 and 5 first.
translatedIncidentTypes is normalized across providers, so you do not need provider-specific mapping.

Accident notification payload (`type = 1`)

Payload fields for accident notifications. The whole delivery is serialized as camelCase, including the data object.

eventId
eventTime
vin
connection
tSP (note the casing: the serializer lowercases only the first letter of TSP)
location (an object with latitude and longitude)
notificationLevel (1 first detection, 2 verified, 3 report-ready)
reportReady
isAccurate

Sample delivery:

{
  "timestamp": "2026-06-17T14:32:05Z",
  "type": 1,
  "data": {
    "eventId": "8d2b1f4a-6c11-4f2e-9b77-1a3c5e9d0f21",
    "eventTime": "2026-06-17T14:30:58Z",
    "vin": "1HGCM82633A004352",
    "connection": "3f2a9c10-7d44-4b8e-bf61-2c9a0e6d4471",
    "tSP": "samsara",
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194
    },
    "notificationLevel": 2,
    "reportReady": false,
    "isAccurate": true
  }
}

notificationLevel tells you where the accident is in the lifecycle. Expect up to three deliveries, one per level.
reportReady indicates whether the full report is available. It typically becomes true at level 3.
isAccurate reflects whether the detection has been verified.
Treat eventId as the key that ties the three levels together.
tSP is intentional. Key on tSP, not TSP or tsp.

Webhook configuration

These fields apply to create and update requests.

connectionIds is the list of connection UUIDs the webhook is scoped to.
url is the endpoint Manifold calls to deliver notifications. It must use HTTPS. A non-HTTPS URL is rejected with 400 Invalid URL, must use 'https'.
httpVerb is the verb Manifold uses when calling your URL. Use POST or PUT.
headers is a map of custom headers Manifold includes on each delivery.
notificationTypes is the list of types to subscribe to (1 accident, 2 event). At least one value is required.

The response adds two read-only fields:

id is the webhook UUID.
createdAt is the UTC timestamp when the webhook was created.

Note: the spec does not define a delivery signature. Use headers to add an inbound token or shared secret so you can verify that a delivery came from your webhook.

Endpoints

List webhooks

Retrieve all webhooks configured for the current account.

Method and path: GET /webhooks
When to use it: to audit existing webhooks, confirm subscriptions, or reconcile config before changes.
Required headers: X-API-KEY
Query parameters: none defined.

curl -X GET "https://api.analytics.autos/webhooks" \
  -H "X-API-KEY: sample_api_key_8a1f2c"

Example response:

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "id": "5e1d8b3a-44c2-4f9e-90a7-7c2b6d1e4f08",
      "connectionIds": ["3f2a9c10-7d44-4b8e-bf61-2c9a0e6d4471"],
      "url": "https://hooks.fleetco.example/manifold",
      "httpVerb": "POST",
      "headers": {
        "X-Webhook-Token": "sample_inbound_token"
      },
      "createdAt": "2026-05-02T09:14:33Z",
      "notificationTypes": [1, 2]
    }
  ]
}

Notes and edge cases:

This endpoint returns all webhooks for the account. It does not paginate. The response model can include a next field, but the list never sets it.
Returns 400 on a bad request and 429 when rate limited.

Create webhook

Method and path: POST /webhook
When to use it: during onboarding, or when adding a new subscription or destination.
Required headers: X-API-KEY, Content-Type: application/json

curl -X POST "https://api.analytics.autos/webhook" \
  -H "X-API-KEY: sample_api_key_8a1f2c" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionIds": ["3f2a9c10-7d44-4b8e-bf61-2c9a0e6d4471"],
    "url": "https://hooks.fleetco.example/manifold",
    "httpVerb": "POST",
    "headers": {
      "X-Webhook-Token": "sample_inbound_token"
    },
    "notificationTypes": [1, 2]
  }'

Example response:

{
  "status": 200,
  "message": "Webhook created successfully",
  "data": {
    "id": "5e1d8b3a-44c2-4f9e-90a7-7c2b6d1e4f08",
    "connectionIds": ["3f2a9c10-7d44-4b8e-bf61-2c9a0e6d4471"],
    "url": "https://hooks.fleetco.example/manifold",
    "httpVerb": "POST",
    "headers": {
      "X-Webhook-Token": "sample_inbound_token"
    },
    "createdAt": "2026-06-17T14:00:00Z",
    "notificationTypes": [1, 2]
  }
}

Notes and edge cases:

notificationTypes must contain at least one value. Use [2] for events only, [1] for accidents only, or [1, 2] for both.
Success returns 200, not 201.
Returns 429 when rate limited. Common 400 cases: a non-HTTPS URL (Invalid URL, must use 'https'), a duplicate URL (Webhook with this URL already exist), and connection IDs not owned by the account (Invalid connection ids).

Update webhook

Update an existing webhook, including its subscribed notification types.

Method and path: PUT /webhook/{id}
When to use it: to change the destination URL, headers, scoped connections, or subscriptions.
Required headers: X-API-KEY, Content-Type: application/json
Path parameter: id is the webhook UUID. Required.

curl -X PUT "https://api.analytics.autos/webhook/5e1d8b3a-44c2-4f9e-90a7-7c2b6d1e4f08" \
  -H "X-API-KEY: sample_api_key_8a1f2c" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionIds": ["3f2a9c10-7d44-4b8e-bf61-2c9a0e6d4471"],
    "url": "https://hooks.fleetco.example/manifold/v2",
    "httpVerb": "POST",
    "headers": {
      "X-Webhook-Token": "sample_inbound_token"
    },
    "notificationTypes": [2]
  }'

Example response:

{
  "status": 200,
  "message": "Webhook updated successfully",
  "data": {
    "id": "5e1d8b3a-44c2-4f9e-90a7-7c2b6d1e4f08",
    "connectionIds": ["3f2a9c10-7d44-4b8e-bf61-2c9a0e6d4471"],
    "url": "https://hooks.fleetco.example/manifold/v2",
    "httpVerb": "POST",
    "headers": {
      "X-Webhook-Token": "sample_inbound_token"
    },
    "createdAt": "2026-05-02T09:14:33Z",
    "notificationTypes": [2]
  }
}

Notes and edge cases:

Update replaces the configuration. Send the full set of notificationTypes you want, not just the change.
Returns 429 when rate limited. Common 400 cases: a non-HTTPS URL (Invalid URL, must use 'https'), a duplicate URL (Webhook with this URL already exist), and connection IDs not owned by the account (Invalid connection ids).

Delete webhook

Remove an existing webhook.

Method and path: DELETE /webhook/{id}
When to use it: to stop deliveries for a destination that is being retired.
Required headers: X-API-KEY
Path parameter: id is the webhook UUID. Required.

curl -X DELETE "https://api.analytics.autos/webhook/5e1d8b3a-44c2-4f9e-90a7-7c2b6d1e4f08" \
  -H "X-API-KEY: sample_api_key_8a1f2c"

Example response:

{
  "status": 200,
  "message": "Webhook deleted successfully",
  "data": true
}

Notes and edge cases:

Deletion takes effect immediately. The webhook stops receiving notifications for all previously subscribed types.
An unknown or not-owned id returns 400 Invalid webhook id.
Returns 429 when rate limited.

Notification types

Event notifications

Accident notifications

Delivery envelope

Event notification payload (type = 2)

Accident notification payload (type = 1)

Webhook configuration

Endpoints

List webhooks

Create webhook

Update webhook

Delete webhook

Event notification payload (`type = 2`)

Accident notification payload (`type = 1`)