Skip to main content
A sensor sends readings in. A device that acts, an irrigation controller, a valve, an alarm or a system of your own, needs the events coming out. A webhook posts each farm event to an HTTPS endpoint that device or its controller exposes, signed, with retries. This guide shows you how to set one up. You need the Manager role or higher on the farm and an HTTPS endpoint. Create a webhook under Settings → Webhooks in the app.

How Delivery Works

Each stored event is posted to your endpoint as a JSON body with a signature header; a 2xx response counts as delivered, and anything else, or a timeout, is retried on the schedule below.

Events

metric.value is high volume. Ten sensors reporting every 15 minutes is around a thousand events a day. For a dashboard that refreshes on a timer, poll the API instead.

Receive The Request

Each delivery is a POST to your endpoint with a JSON body.
Return any 2xx to acknowledge. The response body isn’t inspected.

Verify The Signature

X-Agrihub-Signature is t=<epoch-ms>,v1=<hex>. v1 is the HMAC-SHA256 of "<t>.<raw-body>", keyed with your signing secret.
Sign the raw request body, not a re-serialised object, or the signature won’t match. Reject any t older than a few minutes, or a captured delivery can be replayed.

Retries

  • Delivery times out after 10 seconds. Acknowledge first, then process.
  • Failed deliveries retry at 30s, 2m, 10m, 30m, 2h, 6h, 12h: 8 attempts over about 21 hours.
  • 5xx, 408, 429, timeouts and connection failures are retried. Other 4xx aren’t.
  • After 5 consecutive failed chains the webhook is disabled. Re-enable it in settings. That resets the counter.
  • The delivery log keeps every attempt, with response status and body, for 30 days.
Deliveries are at-least-once and can arrive concurrently. Deduplicate on the event id. Sort on occurred_at_ms if order matters.

Security

  • Endpoints must be HTTPS and can’t point at localhost, private ranges or link-local addresses.
  • Redirects aren’t followed. A 302 is a failed delivery.
  • To rotate a secret, delete the endpoint and create it again.
  • The signing secret can be re-read in settings. A device API key can’t.
That’s it. You have signed events arriving at your endpoint. Next: AgriHub360 Sensor.