EmitLedger Documentation
Contents Overview

Webhooks

Have another system told when a period is approved or locked, results change, an import finishes and more; set up endpoints, verify signatures and read the delivery log.

A webhook tells another system when something happens in your organisation, instead of that system asking again and again. Each endpoint receives an HTTPS POST for the events it subscribes to. Webhooks are managed by client admins under Settings → Webhooks, and need API access in your plan, like API keys.

The Webhooks page with the form for a new endpoint, the list of endpoints and the delivery log.

Events

EventWhen it is sent
period.submittedA month is submitted for review
period.rejectedA submitted or reviewed month is sent back to open
period.approvedA month is approved
period.lockedA month is locked
results.recalculatedA calculation run changed results
import.committedAn Excel or mapped import is committed
import.failedAn import failed validation or could not be processed
reconciliation.decidedA measurement reconciliation decision is recorded
restatement.approvedA restatement is approved and its months reopened
report.readyA requested report or export has finished
verification.rfi.raisedA verifier raises a request for information
verification.rfi.answeredA request for information is answered
ldar.overdueThe weekly reminder finds overdue LDAR surveys or repairs

Payloads carry identifiers and states only, never emissions values or free text. To read the details, call the partner API with a Read key.

Add an endpoint

  1. Under Add an endpoint, enter the Endpoint URL. It must start with https://, and addresses in private or internal networks are refused. Redirects are not followed.
  2. Optionally add a Description, and tick the Events it should receive.
  3. Click Add endpoint. The signing secret is shown once: copy it into the receiving system.
  4. Click Send test to queue a test ping and check the receiver in the Deliveries log.

An organisation can have a limited number of endpoints. To change an endpoint’s address, create a new endpoint and delete the old one.

Verify a request

Every request carries these headers:

HeaderContent
X-Webhook-IdThe delivery id. It is the same on every retry, so use it to ignore repeats
X-Webhook-EventThe event name
X-Webhook-TimestampThe time of this attempt, in Unix seconds
X-Webhook-Signaturev1= followed by the HMAC-SHA256 of the timestamp, a dot and the raw body, using the signing secret, in hexadecimal

Check the signature on the raw body before you parse it, compare it in constant time, and refuse requests whose timestamp is more than a few minutes old. Answer with any 2xx status within 10 seconds; do the real work afterwards.

Retries and failures

Anything other than a 2xx answer, a timeout or a connection error is a failed attempt. Failed deliveries are retried with growing delays up to a fixed number of attempts, then marked failed. Delivery is at least once, so a receiver must cope with the same event twice.

An endpoint that keeps failing is disabled after failures and stops receiving events. Fix the receiver and click Enable; the failure count starts again.

Manage endpoints

  • Disable pauses an endpoint and Enable resumes it.
  • Rotate secret replaces the signing secret. The old one stops working at once, so update the receiver at the same time.
  • Delete removes the endpoint and its delivery log.
  • Deliveries lists each event with its status, HTTP code, number of attempts and last error. Entries are kept for a limited time.

Adding, changing and deleting endpoints is recorded in the audit log.