Webhook Integration

​

Overview

• Delivery: HTTP POST requests to your configured endpoint
• Retry Logic: Automatic retries with exponential backoff
• Supported Events: Prescription lifecycle events (created)

​

How Webhooks Work

1. An event occurs in Parchment (e.g., a prescription is created)
2. Parchment sends an HTTPS POST request to your webhook endpoint
3. Your application processes the event
4. Your endpoint returns a 2xx status code to confirm receipt

​

Configuration

​

Provide Your Webhook Endpoint

• Your webhook endpoint URL (must be HTTPS)
• Your partner ID

​

Webhook Endpoint Requirements

​

1. Use HTTPS

✅ https://api.yourapp.com/webhooks/parchment
❌ http://api.yourapp.com/webhooks/parchment

​

2. Return Success Quickly

// ✅ Good - acknowledge immediately, process later
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  processWebhookAsync(req.body);
});

​

3. Handle Retries Idempotently

async function processWebhook(event) {
  // Check if we've already processed this event
  if (await eventExists(event.event_id)) {
    console.log('Event already processed:', event.event_id);
    return;
  }

  // Process the event
  await handleEvent(event);

  // Mark as processed
  await saveProcessedEvent(event.event_id);
}

​

Webhook Delivery

​

Headers

​

Retry Behavior

• Retries: Up to 3 attempts
• Backoff: Exponential (1s, 2s, 4s)
• Non-retryable errors: 4xx errors (except 408, 429)
• Timeout: 10 seconds per attempt

​

Success Criteria

1. Responds with a 2xx status code (200-299)
2. Within 10 seconds

​

Event Types