Webhooks let you notify an external system automatically whenever an Event or Observation is created (or, for Events, also modified) in EarthRanger  without needing that system to repeatedly check for updates.

Before you begin, you'll need admin access, and a destination URL from the system you want to notify.

• Use an HTTPS URL. EarthRanger doesn't currently restrict webhook destinations to HTTPS, so an http:// URL sends your configured header values — including any tokens — over the network unencrypted.
• Don't point a webhook at an internal or private network address. The destination URL isn't currently checked against internal, loopback, or cloud-metadata addresses, so only use this for an external endpoint you intend to reach.
• Don't treat Request Headers as a secure place for secrets. Header values are stored and shown in plain text in the admin panel, visible to anyone with admin access to that setting.

Setting up an Event Webhook

1. In EarthRanger Admin, go to Activity > Event Webhooks.
2. You'll see a list of your existing Event Webhooks. Select Add Event Webhook in the top right.
3. Fill in:
   • Name — to identify the webhook later.
   • Active — check this to enable it.
   • Send webhook on — choose Event Creation, Event Modification, or Both.
   • URL — the destination that will receive the webhook data.
   • Event Types — select one or more Event Types this webhook should apply to. Leave empty to apply to all Event Types.
   • Request Headers — add any name/value pairs your receiving system needs (for example, an API key).
4. Save using one of: Save, Save and add another, or Save and continue editing.

Setting up an Observation Webhook

1. In EarthRanger Admin, go to Activity > Observation Webhooks.
2. You'll see a list of your existing Observation Webhooks. Select Add Observation Webhook in the top right.
3. Fill in:
   • Name — to identify the webhook later.
   • Active — check this to enable it.
   • Send webhook on — set to Observation Creation. 
   • URL — the destination that will receive the webhook data.
   • Subject Groups — select one or more Subject Groups this webhook should apply to. Leave empty to apply to all Subject Groups. Selecting a group also includes its subgroups.
   • Request Headers — add any name/value pairs your receiving system needs.
4. Save using one of: Save, Save and add another, or Save and continue editing.

What to expect after setup

Webhooks don't always fire the instant something happens since EarthRanger groups everything that's occurred since the last time the webhook fired and sends it together. This happens either right when a matching Event or Observation is saved, or automatically every 60 seconds, whichever comes first.

To keep from overwhelming your receiving system, EarthRanger limits how often webhooks send (2 times per minute by default) and how much data goes in each one (10 items per call by default). If more activity happens than fits, users can expect it to be sent in the next call rather than lost. A short delay during a busy period is expected behavior, not a problem with your webhook.

Troubleshooting

My webhook isn't firing. Check that it's marked Active, and confirm your Event Type or Subject Group filter isn't unintentionally excluding the activity you're expecting.

Data is arriving later than expected. This is usually the batching and rate limits described above — see "What to expect after setup."

I need to fire on Observation modification, not just creation. This isn't currently supported for Observation Webhooks — only creation triggers them.