LivePin Logo

Webhooks

Livepin delivers every vehicle notification to your webhook URL in real time — SOS alerts, overspeed events, geofence entries/exits, and more. You get a POST request to your endpoint for each notification, so you can react instantly in your own platform.

Configure a webhook

Webhooks are managed from the Livepin dashboard:

  1. Go to app.livepin.in and log in.
  2. Open your Profile page from the top-right menu.
  3. Switch to the Webhooks tab.
  4. Review your current webhooks. Use Add webhook to create a new one, or Edit/Delete existing entries.
  5. To add a webhook, provide:
    • Webhook URL — the HTTPS endpoint on your server that receives notifications.
    • Webhook secret — a shared secret used to verify the integrity of every payload.
  6. Save. Livepin starts sending notifications to your URL immediately.

Use https:// URLs only. Livepin will not deliver payloads to insecure endpoints.

Verify the secret

With every payload, Livepin sends the secret you configured in the X-Webhook-Secret header:

X-Webhook-Secret: <YOUR_WEBHOOK_SECRET>

Always verify this header before processing the payload:

  1. Read the X-Webhook-Secret header from the incoming request.
  2. Compare it against the secret you configured, using a constant-time comparison.
  3. Reject the request with 401 if it does not match.

This prevents attackers from sending forged notifications to your endpoint.

Payload format

For every vehicle notification, Livepin sends a POST request to your webhook URL. The delivery payload looks like this:

Webhook delivery

POST
Your webhook URL
{
  "date": 1786308781186,
  "headers": {
    "Accept": ["application/json, text/plain, */*"],
    "Accept-Encoding": ["gzip, compress, deflate, br"],
    "Content-Length": ["284"],
    "Content-Type": ["application/json"],
    "User-Agent": ["axios/1.18.1"],
    "X-Webhook-Secret": ["<YOUR_WEBHOOK_SECRET>"]
  },
  "content_length": 284,
  "body": "{\"notification\":{\"description\":\"Emergency alert triggered, please check the vehicle\",\"imei\":\"377079642594\",\"notification_type\":\"sos\",\"server_timestamp\":1786308720000,\"timestamp\":1786308731000,\"title\":\"Emergency Alert\",\"location\":{\"latitude\":13.126907,\"longitude\":80.207436}},\"user\":1}",
  "method": "POST",
  "path": "/jimiiot",
  "query": ""
}

Headers vary by environment. In addition to the ones above you may also see forwarding headers such as X-Forwarded-For, X-Real-Ip, and X-Request-Start. Only X-Webhook-Secret is significant for verification.

FieldTypeDescription
datenumberDelivery timestamp in milliseconds since epoch.
headersobjectIncoming request headers, including X-Webhook-Secret.
content_lengthnumberByte size of the body string.
bodystringStringified JSON containing the notification. Parse it with JSON.parse().
methodstringAlways POST.
pathstringThe path of the webhook URL that received the payload.
querystringQuery string of the webhook URL, empty when not configured.

Parsed body

The body field is a JSON string. Once parsed, it contains the actual notification:

Parsed body

{
  "notification": {
    "title": "Emergency Alert",
    "description": "Emergency alert triggered, please check the vehicle",
    "notification_type": "sos",
    "imei": "377079642594",
    "timestamp": 1786308731000,
    "server_timestamp": 1786308720000,
    "location": {
      "latitude": 13.126907,
      "longitude": 80.207436
    }
  },
  "user": 1
}

Notification fields

  • Name
    notification.title
    Type
    string
    Description

    Human-readable title of the notification.

  • Name
    notification.description
    Type
    string
    Description

    Short description of the event.

  • Name
    notification.notification_type
    Type
    string
    Description

    Machine-readable event type (for example sos, overspeed, geofence).

  • Name
    notification.imei
    Type
    string
    Description

    IMEI of the vehicle tracker that triggered the event.

  • Name
    notification.timestamp
    Type
    number
    Description

    Event timestamp in milliseconds since epoch.

  • Name
    notification.server_timestamp
    Type
    number
    Description

    Server processing timestamp in milliseconds since epoch.

  • Name
    notification.location.latitude
    Type
    number
    Description

    Latitude of the vehicle at event time.

  • Name
    notification.location.longitude
    Type
    number
    Description

    Longitude of the vehicle at event time.

  • Name
    user
    Type
    number
    Description

    Livepin user ID that owns the vehicle.

Example integration

A minimal Node.js receiver that verifies the secret and handles the notification:

Express receiver

const crypto = require('crypto')
const express = require('express')

const app = express()
app.use(express.json())

// Same value configured in the Webhooks tab of your profile.
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET

app.post('/webhooks/livepin', (req, res) => {
  // 1) Verify the webhook secret (constant-time comparison).
  const received = req.get('X-Webhook-Secret')
  const expected = Buffer.from(WEBHOOK_SECRET)
  if (
    !received ||
    received.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(received), expected)
  ) {
    return res.status(401).json({ error: 'invalid secret' })
  }

  // 2) Parse the stringified body.
  const { notification, user } = JSON.parse(req.body.body)

  // 3) ACK fast, then process asynchronously.
  res.status(200).json({ received: true })
  handleNotification(notification, user)
})

function handleNotification(notification, user) {
  console.log(`[${notification.notification_type}] ${notification.title}`, {
    imei: notification.imei,
    user,
    location: notification.location,
    timestamp: notification.timestamp,
  })
}

Manage webhooks via API

Webhooks can also be managed programmatically instead of through the dashboard. Every call requires the x-api-key and Authorization: Bearer headers.

  • Name
    GET /api/user-webhooks
    Description
    List your webhooks.
  • Name
    GET /api/user-webhooks/:id
    Description
    Get one webhook.
  • Name
    POST /api/user-webhooks
    Description
    Create a webhook (url + secret).
  • Name
    PUT /api/user-webhooks/:id
    Description
    Update a webhook.
  • Name
    DELETE /api/user-webhooks/:id
    Description
    Delete a webhook.

Create webhook

curl -X POST "$LIVEPIN_API_BASE_URL/api/user-webhooks" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-platform.com/webhooks/livepin","secret":"<YOUR_WEBHOOK_SECRET>"}'

List webhooks

curl "$LIVEPIN_API_BASE_URL/api/user-webhooks" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Delete webhook

curl -X DELETE "$LIVEPIN_API_BASE_URL/api/user-webhooks/:id" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Best practices

  • Always verify the X-Webhook-Secret header before processing any payload.
  • Return 2xx as fast as possible and process business logic asynchronously.
  • Make handlers idempotent using notification.server_timestamp + notification.imei.
  • Store the secret in an environment variable, never in source code.
  • Regenerate the secret from the Webhooks tab if it is ever exposed.
  • Log delivery failures and alert if webhooks stop arriving.

Was this page helpful?