Integration Guide for Partners

Quick Start

Four steps to start receiving events from AgricVue.

1. 1

   Create an API Key

   In the AgricVue dashboard go to Settings → API Keys. Create a key with the "webhooks" scope.

2. 2

   Authenticate

   Include the key in every request as X-API-Key header.

3. 3

   Create a Webhook Subscription

   POST to /api/v1/webhooks with your URL and the event types you want. Save the signing_secret returned in the response.

4. 4

   Receive Events

   AgricVue will POST JSON payloads to your URL with HMAC-SHA256 signatures for verification.

Authentication

All API requests require an X-API-Key header.

curl -H "X-API-Key: agr_sk_your_key_here" \
     https://api.agricvue.com/api/v1/farms

Scopes

Webhook Setup

Create a Subscription

curl -X POST https://api.agricvue.com/api/v1/webhooks \
  -H "X-API-Key: agr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/agricvue",
    "event_types": ["farm.created", "monitoring.completed", "harvest.ready"],
    "description": "Production webhook"
  }'

Response includes a signing_secret shown only once. Store it securely for verifying incoming payloads.

Manage Subscriptions

Event Types Reference

Subscribe to one or more of these events.

{
  "event": "farm.created",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "name": "Adekunle Rice Farm",
    "area_hectares": 12.5,
    "location": "Kebbi State",
    "country": "Nigeria"
  }
}

{
  "event": "farm.updated",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "name": "Adekunle Rice Farm",
    "changes": ["farm_name", "current_use"]
  }
}

{
  "event": "monitoring.completed",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "result_id": "uuid",
    "ndvi": 0.72,
    "health_status": "healthy",
    "trend": "improving"
  }
}

{
  "event": "harvest.ready",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "score": 82,
    "crop": "rice",
    "estimated_date": "2026-04-15"
  }
}

{
  "event": "disease.detected",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "disease": "Rice Blast",
    "confidence": 0.94,
    "severity": "moderate"
  }
}

{
  "event": "weather.advisory",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "advisory_id": "uuid",
    "severity": "warning",
    "summary": "Heavy rainfall expected (45mm) in next 24h..."
  }
}

{
  "event": "analysis.completed",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "analysis_id": "uuid",
    "score": 78.5,
    "class": "suitable"
  }
}

{
  "event": "credit_score.updated",
  "event_id": "uuid",
  "timestamp": "2026-03-19T10:00:00Z",
  "data": {
    "farm_id": "uuid",
    "score": 72,
    "risk_class": "good"
  }
}

Webhook Security

Every webhook delivery includes an X-AgricVue-Signature header containing an HMAC-SHA256 signature of the payload body. Always verify this before processing.

Headers Sent

Verification Examples

import hmac, hashlib

def verify_webhook(payload_bytes: bytes, secret: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"), payload_bytes, hashlib.sha256
    ).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

const crypto = require("crypto");

function verifyWebhook(body, secret, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const received = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(received)
  );
}

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strings"
)

func VerifyWebhook(body []byte, secret, sigHeader string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    received := strings.TrimPrefix(sigHeader, "sha256=")
    return hmac.Equal([]byte(expected), []byte(received))
}

Delivery & Retries

• Success:Any 2xx HTTP status code
• Timeout:10 seconds per attempt
• Payload limit:Response body is truncated to 2,000 characters in logs

Error Handling

The API returns standard HTTP status codes with JSON error bodies.

{
  "detail": "API key does not have the 'webhooks' scope"
}

Testing

Use the test endpoint to send a ping event to your webhook URL without waiting for a real event to fire.

curl -X POST https://api.agricvue.com/api/v1/webhooks/{id}/test \
  -H "X-API-Key: agr_sk_your_key_here"

The test endpoint sends a synchronous request and returns the result immediately:

{
  "success": true,
  "status_code": 200,
  "error": null
}

Lender Portfolio Monitoring

Continuous visibility into crop health across your entire loan book. Authenticated via X-API-Key (lender API keys, format: agr_live_...).

Parametric Insurance Data API

Weekly crop stress indices, risk profiles, and automatic claim triggering for insurers. Authenticated via X-API-Key (insurer keys, format: agr_ins_...).

Parametric Triggers

Claims auto-trigger when satellite data crosses these thresholds (configurable per policy):

Farm Verification & Compliance Reports

Fraud detection scores, satellite-verified land use proof, and regulatory compliance exports.

Verification Score Components

Fraud Flag Types

Compliance Report Types

Community Alerts, Insurance & Certificates

Farmer-facing endpoints for disease alerts, insurance enrollment, and harvest certificates. Authenticated via JWT or tenant API key.