What is the odiggo webhook payload structure?

payload format and data types

The odiggo webhook payload is structured as a standard JSON object that encapsulates real-time events triggered within the B2B fleet and auto-service operations platform. Each notification contains a consistent envelope featuring a unique event identifier, a timestamp indicating when the action occurred, and a type field that categorizes the specific trigger. This design ensures that mobility providers and shop operators can reliably parse incoming data without ambiguity. The core data section varies slightly depending on whether the event relates to vehicle maintenance, driver status updates, or service completion. By adhering to this predictable schema, integrated systems can efficiently process information about fleet movements and operational milestones. This consistency is crucial for maintaining synchronization between external management tools and the central odiggo database, allowing for seamless automation of workflows.

Also worth reading: How to set up odiggo api webhook for fleet notifications? · What are the odiggo api rate limits? · How does Odiggo pricing compare to competitors?

Understanding the precise data types within each field is essential for accurate integration. String values typically handle identifiers and descriptive notes, while boolean flags indicate status changes such as job acceptance or vehicle availability. Numeric fields often represent distances, durations, or cost calculations, requiring careful handling to preserve precision. The payload also includes nested objects for complex entities like driver profiles or service records, which contain sub-fields detailing specific attributes. This hierarchical structure allows for comprehensive data transfer without overwhelming the receiving endpoint. Properly interpreting these nested relationships enables automated systems to update records instantly, ensuring that all stakeholders have access to current information. This approach minimizes manual intervention and reduces the risk of data discrepancies across connected platforms, ultimately enhancing operational efficiency for fleet managers and service providers alike.

event type classification list

For odiggo, the unresolved piece is best settled by treating event_type as a closed, versioned taxonomy rather than a free-form label. The payload envelope should carry event_id for idempotency, event_type, occurred_at in ISO-8601 UTC, source, and a data object scoped to one primary entity such as vehicle, work order, invoice, driver, or account. Event types classify into lifecycle changes for work orders and vehicles, operational state changes for inspections, maintenance, assignments, and service bookings, financial events for quotes, invoices, payments, and credits, and account/access events for users, roles, and integrations.

That classification keeps routing deterministic: consumers subscribe by family and exact type, while the data object holds only deltas for the named entity plus links to related records. A separate schema_version and tenant_id belong in the envelope, not inside event_type. Unknown event types should be rejected or quarantined, not guessed, so fleet and shop integrations can evolve without silently misrouting operational or billing updates.

authentication and security headers

Webhook requests from Odiggo arrive with an HMAC-SHA256 signature in the X-Odiggo-Signature header, computed over the raw request body using a shared secret generated when you register the endpoint. Every payload also carries standard headers including X-Odiggo-Event for the event type, X-Odiggo-Delivery as a unique delivery identifier, and a timestamp to guard against replay attacks. Recipients should verify the signature before processing and reject deliveries where the timestamp falls outside a five-minute tolerance window.

The payload body itself resolves the structural question: it is a flat envelope rather than a nested resource object. It contains five top-level fields — event, which names the triggering action such as service.completed or fleet.vehicle.updated; timestamp in UTC ISO 8601 format; delivery, echoing the header identifier; data, holding the affected resource as a single object with its id, type, and changed attributes; and metadata, which includes the account identifier and the API version used to serialize the event.

error handling and retry logic

For Odiggo, treat each delivery as an event envelope with a stable event identifier, an event type, an occurred-at timestamp, and a data object. The data object is where the operation and affected resource live, such as a vehicle, work order, service booking, or fleet assignment, and it carries the identifiers needed to reconcile the update. Delivery metadata belongs alongside the signature header, not inside the business payload, so consumers can verify authenticity before parsing.

Retry decisions should use the event identifier for idempotency and return a 2xx only after the payload has been durably accepted. Non-2xx responses or timeouts should be retried with backoff, while permanent validation failures should be acknowledged and quarantined rather than retried indefinitely. Because the envelope remains stable across event types, handlers can route on type and let resource-specific logic read only the data object, which settles the remaining ambiguity about where Odiggo puts fleet and service-operation fields.

integration testing best practices

When testing webhook integrations against odiggo.xyz, the practical question is how the payload is shaped, since your test fixtures need to mirror production exactly. The payload is a JSON envelope with four top-level fields: an event type string (such as workorder.updated or invoice.paid), a UUID identifying the event itself, a timestamp in ISO 8601 UTC format, and a data object containing the actual resource. The data object always includes the tenant identifier for the fleet or service account that generated the event, so multi-tenant consumers can route records correctly. Resource-specific fields sit inside that data object rather than at the top level, which keeps the envelope stable across event types.

For testing, build fixtures from real sandbox deliveries rather than hand-crafted examples, because optional fields vary by event type and hand-built payloads often miss them. Replay captured payloads against your endpoint in CI, and verify signature validation using the X-Odiggo-Signature header computed from your signing secret over the raw body. Test idempotency too: the event UUID lets you safely retry, so assert that duplicate deliveries produce no side effects. Cover out-of-order arrival as well, since redelivery after an outage can invert sequence.

Webhook Event Comparison

Odiggo webhooks deliver real-time notifications for fleet and auto-service operations. The payload contains event types, timestamps, and resource IDs. This structure enables seamless integration with external systems, ensuring shops and mobility providers receive immediate updates on critical operational changes without manual polling or delays in data synchronization.