Skip to main content

​
Overview

Webhooks allow you to receive HTTP POST requests when specific events occur in your MedStrato organization. Use webhooks to:
  • Sync KOL data to your CRM in real-time
  • Trigger workflows when campaigns are sent
  • Update external systems when event RSVPs change
  • Monitor regulatory signals as they arrive

​
Setting Up Webhooks

​
1. Create a Webhook Endpoint

Create an endpoint in your application that accepts POST requests: 
// Example Express.js endpoint
app.post('/webhooks/stratosphere', (req, res) => {
  const signature = req.headers['x-stratosphere-signature'];
  const payload = req.body;

  // Verify signature
  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  switch (payload.event) {
    case 'kol.created':
      handleKolCreated(payload.data);
      break;
    case 'campaign.sent':
      handleCampaignSent(payload.data);
      break;
    // ... handle other events
  }

  res.status(200).send('OK');
});

​
2. Register Your Webhook

curl -X POST "https://api.getstrato.dev/v1/webhooks" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/stratosphere",
    "events": ["kol.created", "kol.updated", "campaign.sent"],
    "secret": "your_webhook_secret"
  }'

​
Webhook Events

​
KOL Events

EventDescription
kol.createdA new KOL was added
kol.updatedA KOL profile was updated
kol.archivedA KOL was archived
kol.tier_changedA KOL’s tier was changed

​
Event Events

EventDescription
event.createdA new event was created
event.updatedAn event was updated
event.cancelledAn event was cancelled
event.attendee_addedAn attendee was added
event.rsvp_updatedAn RSVP status changed

​
Campaign Events

EventDescription
campaign.createdA new campaign was created
campaign.sentA campaign was sent
campaign.email_openedA recipient opened an email
campaign.link_clickedA recipient clicked a link

​
Signal Events

EventDescription
signal.newA new regulatory signal was detected
signal.high_impactA high/critical impact signal was detected

​
Webhook Payload

All webhook payloads follow this structure: 
{
  "id": "wh_evt_abc123",
  "event": "kol.created",
  "created_at": "2024-01-20T14:30:00Z",
  "data": {
    "id": "kol_xyz789",
    "full_name": "Dr. Sarah Chen",
    "tier": "tier_1",
    // ... event-specific data
  },
  "organization_id": "org_abc123"
}

​
Verifying Signatures

MedStrato signs all webhook payloads using HMAC-SHA256. Verify signatures to ensure requests are authentic: 
const crypto = require('crypto');

function verifySignature(payload, signature) {
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

import hmac
import hashlib

def verify_signature(payload: str, signature: str) -> bool:
    expected = hmac.new(
        key=WEBHOOK_SECRET.encode(),
        msg=payload.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

​
Retry Policy

If your endpoint returns a non-2xx status code, MedStrato will retry the webhook:
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry24 hours
After 5 failed attempts, the webhook will be marked as failed and you’ll receive an email notification.

​
Managing Webhooks

​
List Webhooks

curl -X GET "https://api.getstrato.dev/v1/webhooks" \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Update Webhook

curl -X PATCH "https://api.getstrato.dev/v1/webhooks/wh_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["kol.created", "kol.updated", "signal.high_impact"],
    "enabled": true
  }'

​
Delete Webhook

curl -X DELETE "https://api.getstrato.dev/v1/webhooks/wh_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Testing Webhooks

Use the webhook test endpoint to send a test event: 
curl -X POST "https://api.getstrato.dev/v1/webhooks/wh_abc123/test" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "kol.created"
  }'