Webhooks

Webhooks

AirPinpoint can send webhook notifications to your servers when devices enter or exit your geofences, allowing you to build automated workflows based on location events.

Overview

Webhooks are HTTP callbacks that deliver data to your server when events occur in AirPinpoint. Instead of continuously polling our API, webhooks push data to your application when important events happen - like when a device enters or exits a geofence.

Common Use Cases

• Delivery confirmations: Get notified when a vehicle enters a delivery address geofence
• Equipment tracking: Know when assets arrive at or leave job sites, warehouses, or yards
• Security alerts: Be alerted when items move outside of designated safe zones
• Inventory management: Automatically update inventory systems when items arrive at warehouses
• Customer notifications: Trigger SMS or email notifications to customers when deliveries are approaching

Setting Up Webhooks

To set up a webhook:

1. Create or edit a geofence
2. Select "Webhook" as the notification type
3. Enter your webhook URL - this should be a publicly accessible HTTPS endpoint on your server
4. Optionally add a webhook secret for security

Webhook Payload

When a device enters or exits a geofence, we'll send a POST request to your webhook URL with a JSON payload:

{
  "event": "geofence.entry", // or "geofence.exit"
  "occurred_at": "2023-06-15T13:45:30.123Z",
  "geofence": {
    "id": "f8c3de3d-1234-5678-90ab-cdef01234567",
    "name": "Warehouse A",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 100
  },
  "beacon": {
    "id": "a7b4cd9e-1234-5678-90ab-cdef01234567",
    "name": "Forklift #42",
    "type": "apple"
  },
  "location": {
    "latitude": 37.7750,
    "longitude": -122.4195,
    "accuracy": 10,
    "timestamp": "2023-06-15T13:45:29.000Z"
  }
}

Entry vs. Exit Events

• geofence.entry: Triggered when a tracked device enters a geofence boundary
• geofence.exit: Triggered when a tracked device leaves a geofence boundary

You can use these distinct event types to implement different business logic for arrivals and departures.

Integrating With Your Systems

Webhooks can be integrated with:

• Your own backend servers
• Zapier or Make (formerly Integromat) workflows
• AWS Lambda or Azure Functions
• GitHub Actions or other CI/CD pipelines
• Custom applications that need real-time location data

Webhook Security

To verify webhook requests are coming from AirPinpoint:

1. Set a webhook secret when configuring your webhook
2. We'll include a signature in the X-AirPinpoint-Signature header
3. This signature is an HMAC SHA-256 hash of the request body using your secret as the key
4. Verify this signature on your server to ensure authenticity

Example signature verification in Node.js:

const crypto = require('crypto');
 
function verifyWebhookSignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}
 
app.post('/webhooks/geofence', (req, res) => {
  const signature = req.headers['x-airpinpoint-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, 'your_webhook_secret');
  
  if (!isValid) {
    return res.status(403).send('Invalid signature');
  }
  
  // Process the webhook...
  res.status(200).send('Webhook received');
});

Testing Your Webhooks

Before relying on webhooks in production, you can test your webhook endpoint using our test webhook API:

curl -X POST "https://api.airpinpoint.com/v1/geofences/{geofence_id}/test-webhook" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "eventType": "entry"
     }'

This endpoint will:

1. Find the specified geofence and check if webhook notifications are enabled
2. Send a test payload to your configured webhook URL
3. Return information about the delivery attempt

Example response:

{
  "success": true,
  "message": "Test webhook successfully sent for entry event",
  "deliveryId": "webhook_delivery_123456"
}

If the test fails, you'll receive:

{
  "success": false,
  "message": "Failed to send test webhook. Check your endpoint configuration."
}

You can use the returned deliveryId to check details about the delivery in the webhook delivery history.

Webhook Retries

If your server responds with an error (non-2xx status code), we'll retry the webhook delivery:

• First retry: 5 seconds after initial failure
• Second retry: 30 seconds after first retry
• Third retry: 2 minutes after second retry

Webhook Delivery History

You can view the history of webhook deliveries in the Webhooks section of your dashboard to help debug issues with your webhook endpoint. This includes:

• Success/failure status
• Timestamp of delivery attempts
• HTTP response codes
• Response bodies (truncated for large responses)

This information is invaluable when troubleshooting integration issues between AirPinpoint and your systems.