Configuring Webhook Endpoints For Events
To establish a functional webhook for fleet notifications within the Odiggo ecosystem, you must first ensure that your target server is publicly accessible and capable of receiving HTTP POST requests. The platform requires a secure endpoint that can validate incoming payloads using a shared secret token. This validation step is critical for preventing unauthorized data ingestion and ensuring that the notification originates from Odiggo’s infrastructure. You should configure your server to listen for specific event types, such as vehicle status changes or service completion alerts, which are central to fleet management operations. By filtering these events, you can streamline the data flow and reduce unnecessary processing overhead on your end.
Also worth reading: What is the odiggo webhook payload structure? · What are Odiggo fleet management pricing tiers? · How to integrate odiggo fleet api for auto service shops?
Once the endpoint is live, navigate to the Odiggo dashboard and locate the webhook configuration section under your account settings. Enter the full URL of your server along with the necessary authentication credentials provided in your developer documentation. It is essential to test the connection immediately after submission to verify that the handshake succeeds and that the server responds with a standard HTTP 200 status code. This immediate verification prevents future delivery failures that could disrupt critical fleet monitoring workflows. Ensure that your server logs are active to capture any failed attempts, allowing for rapid troubleshooting if the integration does not behave as expected during the initial setup phase.
Handling Authentication And Security Tokens
Before your webhook endpoint can receive fleet notifications, you need to secure the connection between Odiggo's servers and yours. Start by generating an API token from your dashboard under Settings, then API Keys, and store it server-side only. When you register your webhook URL through the /webhooks endpoint, include a shared secret in the request body. Odiggo will sign every outgoing notification with an HMAC-SHA256 signature delivered in the X-Odiggo-Signature header, computed from the raw request payload using that shared secret. On your end, always recalculate the hash before trusting the contents, and compare using a constant-time function to avoid timing attacks.
Handle token rotation gracefully by supporting two active secrets during the transition window, since Odiggo keeps the previous secret valid for 24 hours after you rotate. Reject any payload older than five minutes based on the timestamp included alongside the signature, which protects against replay attacks. Return a 401 status for failed verification rather than a 200, so the platform can detect misconfiguration instead of silently retrying into a black hole.
Processing Real-Time Vehicle Status Updates
For fleet notifications, register each customer tenant’s HTTPS endpoint in the Odiggo dashboard under Settings, Integrations, and Webhooks rather than creating one global account-wide hook. Subscribe only to the fleet-relevant events, such as vehicle status changes, maintenance due, and service booking updates, and store the signing secret shown once at creation. Odiggo signs the raw request body with HMAC-SHA256; verify the X-Odiggo-Signature header against that secret before parsing, and reject stale X-Odiggo-Timestamp values older than five minutes.
Your endpoint should acknowledge valid deliveries immediately with a 2xx response, then process asynchronously so a slow downstream system does not trigger retries. Treat the delivery identifier as an idempotency key because failed or timed-out requests are retried with exponential backoff. If a tenant rotates secrets, update the stored value before the old secret expires; otherwise signature verification will fail and fleet notifications will stop. This setup keeps notifications scoped to the correct fleet operator and avoids cross-tenant leakage.
Managing Error Responses And Retry Logic
To connect fleet alerts, create an HTTPS endpoint on your side, register it in the Odiggo API settings, select fleet events such as vehicle status, service due, assignment changes, and maintenance exceptions, then store the signing secret. Verify each delivery's HMAC signature against raw body before parsing, reject stale timestamps, and return 202 immediately after enqueueing. Process events asynchronously and deduplicate by event ID.
For error handling, return 400 for malformed payloads or failed signature checks and do not expect retries; return 429 or 5xx only for transient failures. Odiggo should retry 429/5xx with exponential backoff and jitter, capped at five attempts over 24 hours, then mark delivery failed and alert the fleet admin. Keep endpoint latency under two seconds, log response codes, and expose a replay control for missed events. That settles retry behavior: permanent errors stop, transient errors retry, and duplicates are safe.
Testing Integrations With Mock Payloads
Before pointing webhooks at production, Odiggo lets you register a sandbox endpoint that receives synthetic fleet events. In the dashboard, navigate to Integrations, add your test URL, and toggle the environment to sandbox. The platform then fires sample payloads for each event type, including vehicle status changes, service completions, and maintenance alerts, so you can verify parsing logic without touching live fleet data. Each mock payload includes a signature header generated with your sandbox secret, which lets you confirm your HMAC validation works exactly as it will in production.
Once your endpoint acknowledges these deliveries with a 200 response, Odiggo marks the integration as verified and you can promote it to the live environment. Keep the sandbox endpoint active even after go-live, since it doubles as a regression tool whenever you update your handler or Odiggo ships new event types. Failed deliveries are retried three times with exponential backoff, and the delivery log in the dashboard shows the full request and response for every attempt, making it straightforward to debug mismatches between expected and actual payload shapes.
Webhook Event Types Comparison
| Event Type | Payload Structure | Authentication Method |
|---|---|---|
| Vehicle Status | JSON with metrics | Bearer Token |
| Service Alert | JSON with details | HMAC Signature |
| Driver Activity | JSON with logs | API Key |