Webhooks

Webhooks allow you to build or set up integrations, which subscribe to certain events on the app. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL.

Webhooks can be installed on an organization, or a specific account. Once installed, the webhook will be sent each time one or more subscribed events occurs.

Each event corresponds to a certain set of methods that can happen to your organization and/or any other documents under that organization. For example, if you subscribe to the medical-encounters event you'll receive detailed payloads every time a MedicalEncounter is created, updated, or removed.

Creating Webhooks

# create a webhook
POST /webhook-events
{
  "organization": "organization.id",
  # set the webhook as active
  "active": true,
  # URL is the URL of the server that will receive the webhook `POST` requests
  "url": "https://example.com/webhook",
  # events to listen on. pattern: `<service-name>.<method>`
  "events": "ping"
}

# create a webhook
POST /webhook-events
{
  "organization": "organization.id",
  # set the webhook as active
  "active": true,
  # URL is the URL of the server that will receive the webhook `POST` requests
  "url": "https://example.com/webhook",
  # events to listen on. pattern: `<service-name>.<method>`
  "events": "ping"
}

Testing Webhooks

When you create a new webhook, you can also create a ping event to let you test that your webhook is correctly configured.

# create a ping event
POST /webhook-events
{
  "webhook": "webhook.id",
  "event": "ping"
}

# create a ping event
POST /webhook-events
{
  "webhook": "webhook.id",
  "event": "ping"
}

Webhook events and payloads

Each webhook should expect to received a payload with the following schema:

interface WebhookEvent {
  // webhook event id
  id: string;
  // the event the happended
  event: string;
  // payload contains the relevant document
  payload?: object;
}

interface WebhookEvent {
  // webhook event id
  id: string;
  // the event the happended
  event: string;
  // payload contains the relevant document
  payload?: object;
}

The webhook should return with a status code of 200 to mark the webhooks as delivered