Skip to main content

Webhooks

Prepared's Partner API sends real-time notifications to your application when events occur. Webhooks are HTTP POST requests sent to a URL you configure during integration setup.

How Webhooks Work​

  1. An event occurs in Prepared (e.g., incident created, location updated)
  2. Prepared sends an HTTP POST request to your webhook URL
  3. Your server processes the event and returns a 200 status code
  4. If delivery fails, Prepared retries with exponential backoff

Webhook Types by Scope​

CAD Webhooks (cad_incidents scope)​

For CAD provider integrations receiving data back from Prepared:

EventDescription
note_createdAI summary, media link, or incident link added
location_updatedCaller location updated

View CAD Webhooks Schema →

Incident Events Webhooks (incident_events scope)​

For first responder applications receiving incident updates:

EventDescription
incident_metadataIncident created or updated
caller_locationCaller location updated
mediaPhoto, video, or recording attached

View Incident Events Webhooks Schema →

Setting Up Webhooks​

  1. Provide your webhook URL to your Prepared integration contact
  2. Configure authentication — Tell Prepared which method you will use (see Webhook Security below).
  3. Implement webhook handlers for the events relevant to your integration
  4. Return 200 status to acknowledge receipt

Webhook Security​

Per partner, authentication is one of:

  • Auth header / long-lived token — You provide a Bearer token to Prepared; Prepared includes it in the Authorization header when calling your webhook. Your endpoint validates that the token matches what you issued.
  • OAuth client ID + secret — Prepared uses your client_id and client_secret to authenticate when calling your webhook (e.g. obtaining a token per request or using a cached token).

Your webhook endpoint should validate requests using whichever method you and Prepared agreed on.

Best Practices​

  • Respond quickly — Return 200 as soon as possible, then process asynchronously
  • Handle duplicates — Use event IDs to deduplicate if your handler isn't idempotent
  • Log everything — Keep records of webhook payloads for debugging
  • Monitor failures — Set up alerts for webhook processing errors

Example Handler​

app.post('/webhooks/prepared', async (req, res) => {
  // Validate authentication
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!validateToken(token)) {
    return res.status(401).send('Unauthorized');
  }

  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process asynchronously
  const event = req.body;
  await processWebhookEvent(event);
});

Next Steps​