Webhook Ingestion (Plugs)

Plugs Overview#

Plugs is Aforo's webhook receiver — a durable inbound endpoint that transforms raw third-party webhook payloads into normalized Aforo usage events. Instead of writing custom event-parsing code for every provider you integrate, you configure a Plug once in the Aforo UI and point the provider's webhook settings at Aforo.

Aforo handles the hard parts: HMAC signature verification, JSONPath field extraction, deduplication (using the provider's event ID), and delivery retries if your downstream billing pipeline is temporarily unavailable. Your engineering team touches nothing.

Creating a Source#

Navigate to Commercial → Webhook Sources → New Source in the Aforo admin. Each source represents a single provider integration. You can create multiple sources for the same provider — for example, one Stripe source per environment (production, staging).

Source Configuration Fields

After saving, Aforo generates a webhook URL unique to the source:

https://api.aforo.ai/v1/ingest/webhook/wsrc_01HXKRM3ABCDE7F8G9HNPQRST

Paste this URL into the provider's webhook settings dashboard. Aforo begins receiving events immediately.

Signature Verification#

Every inbound request is verified before any payload processing occurs. An unverified or tampered webhook returns 401 Unauthorized and is logged — but never processed. The raw body is never parsed until signature validation passes.

Supported Signature Formats

Verification uses MessageDigest.isEqual() — a constant-time byte comparison — to prevent timing attacks. A missing or empty signing secret returns 401 rather than a 500, so misconfigured sources fail closed and never leak config state to probing attackers.

JSONPath Extraction#

Once a webhook passes signature verification, Aforo applies your JSONPath field mapping to extract the five standard usage event fields from the raw payload. Each mapping is a JSONPath expression that resolves to a scalar value within the provider's JSON body.

Standard Field Mappings

Example: Mapping a Stripe Charge

A Stripe charge.succeeded webhook payload looks like this:

{
  "id":    "evt_1PH2KKLkdIwHu7ix9J0Pu7Ev",
  "type":  "charge.succeeded",
  "data": {
    "object": {
      "id":       "ch_3PH2KKLkdIwHu7ix0G7Xc2q9",
      "amount":   4900,
      "currency": "usd",
      "metadata": {
        "aforo_tenant_id": "tenant_acme_corp",
        "plan":            "professional"
      },
      "created":  1713434800
    }
  }
}

The corresponding JSONPath field mapping in Aforo:

{
  "event_filter": ["charge.succeeded"],
  "field_mappings": {
    "quantity":  "$.data.object.amount",
    "tenant_id": "$.data.object.metadata.aforo_tenant_id",
    "event_id":  "$.id",
    "timestamp": "$.data.object.created",
    "properties": {
      "currency": "$.data.object.currency",
      "plan":     "$.data.object.metadata.plan"
    }
  }
}

Supported Providers#

Built-in provider templates pre-fill the field mappings and signature header configuration. Select a template when creating a source and adjust any fields that differ from the defaults.

Sending a Test Webhook with curl

The example below simulates a Stripe charge.succeeded event being received by Aforo. Replace YOUR_SOURCE_ID with the ID from the source you created and compute the HMAC with your signing secret.

# Compute HMAC-SHA256 signature (Stripe format)
PAYLOAD='{"id":"evt_test_1","type":"charge.succeeded","data":{"object":{"id":"ch_test","amount":4900,"currency":"usd","metadata":{"aforo_tenant_id":"tenant_acme"},"created":1713434800}}}'
TIMESTAMP=$(date +%s)
SECRET="whsec_your_stripe_signing_secret"
SIG=$(echo -n "${TIMESTAMP}.${PAYLOAD}" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

# Send the webhook to Aforo
curl -X POST https://api.aforo.ai/v1/ingest/webhook/wsrc_YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=${TIMESTAMP},v1=${SIG}" \
  -d "$PAYLOAD"

# Expected 200 response
{
  "status":   "accepted",
  "event_id": "evt_test_1",
  "metric_id": "stripe_charges",
  "quantity":  4900,
  "tenant_id": "tenant_acme"
}