Skip to main content

Webhooks & Notifications

Overview​

The Bullitt e-BSS platform provides a robust webhook system that delivers real-time notifications about device activities and system events. Webhooks allow your applications to receive immediate updates rather than polling the API for changes, enabling efficient integrations and timely responses to events.

What are Webhooks?​

Webhooks are HTTP callbacks that deliver data to your systems when events occur in the e-BSS platform. Instead of your application continuously checking for updates, the e-BSS system sends HTTP POST requests to your designated endpoint whenever relevant events occur.

Key Use Cases​

Webhooks are particularly valuable for:

  • Real-time tracking: Receive immediate notifications when devices connect or disconnect
  • Message delivery: Get instant alerts when devices send uplink messages
  • Automated workflows: Trigger business processes based on device activities
  • Live dashboards: Update monitoring dashboards in real-time
  • Event logging: Record all device activities in your own systems

Webhook Configuration​

Setting Up Your Webhook Endpoint​

To receive webhook notifications, you need to:

  1. Create an HTTP endpoint on your server that can receive POST requests
  2. Ensure your endpoint can process JSON payloads
  3. Configure the e-BSS system to send webhooks to your endpoint

Configuring the Webhook​

Use the following API endpoint to configure your webhook:

PUT /organisations/{organisationId}/configure-webhook

Example request:

{
  "endpoint": "https://api.acme.com/bullitt-uplink-message",
  "apiKey": "key_Cf123"
}

The apiKey is a credential you provide that the e-BSS system will include in webhook requests. This allows your endpoint to verify that incoming requests are legitimate.

Testing Your Webhook (Coming Soon)​

After configuration, test your webhook to ensure proper setup:

POST /organisations/{organisationId}/test-webhook

This sends a test notification to your endpoint, allowing you to verify that messages are being received and processed correctly.

Webhook Event Types​

Your webhook endpoint will receive different types of events:

Device Connection Events​

  • Device connects to the satellite network (connected CDR)
  • Device disconnects from the network (disconnected CDR)

Message Events​

  • Device sends an uplink message (message CDR with message payload)
  • Device sends a tracking message (tracking CDR with tracking data)

Webhook Payload Format​

Webhook notifications include both the event data and the corresponding CDR. The detailed format for message aspect of the response can be found at Message Relay Format.

{
  "message": {
    // Message details (if applicable)
  },
  "cdr": {
    // CDR info
  }
}

Note that connected and disconnected CDR events don't include a message field.