Custom Webhooks

Connect any system that can POST JSON with generic HMAC or Bearer authentication.

Generic HMAC connect dialog for a custom webhook trigger

Use custom webhooks when a system can POST JSON but AgentField does not ship a named source for it.

This is the right path for internal services, simple SaaS webhooks, and tools such as Zapier. Zapier is not a native AgentField OSS integration; it can connect by posting to one of these generic sources.

Source Surfaces

Source	Auth	Config	Event type	Idempotency
`generic_hmac`	HMAC-SHA256 over the raw body.	`signature_header`, optional `signature_prefix`, `event_type_header`, `idempotency_header`.	Optional header named by `event_type_header`.	Optional header named by `idempotency_header`.
`generic_bearer`	Constant-time comparison against a bearer token.	`header`, `scheme`, optional `event_type_header`, `idempotency_header`.	Optional header named by `event_type_header`.	Optional header named by `idempotency_header`.

Neither source ships a separate capability node. Put provider-specific behavior in your reasoner.

Generic HMAC

generic_hmac verifies an HMAC-SHA256 signature over the raw request body.

from agentfield import Agent, on_event

app = Agent(node_id="webhook-agent")

@app.reasoner()
@on_event(source="generic_hmac", secret_env="CUSTOM_WEBHOOK_SECRET")
async def handle_signed_webhook(event: dict, trigger=None):
    return {"event_type": trigger.event_type if trigger else "webhook"}

app.run()

Config:

{
  "signature_header": "X-Signature",
  "signature_prefix": "sha256=",
  "event_type_header": "X-Event-Type",
  "idempotency_header": "X-Delivery-ID"
}

Generic Bearer

generic_bearer compares a token in a request header with the secret value from the configured env var.

{
  "header": "Authorization",
  "scheme": "Bearer",
  "event_type_header": "X-Event-Type",
  "idempotency_header": "X-Delivery-ID"
}

Dispatch Contract

Both generic sources dispatch the request body as the normalized event:

{
  "event": {
    "incident_id": "INC-123",
    "severity": "high"
  },
  "_meta": {
    "source": "generic_hmac",
    "event_type": "incident.created",
    "idempotency_key": "delivery-123"
  }
}

Notes

Use HMAC when the sender can sign payloads.
Use Bearer only for trusted systems that can protect a static token.
Set an idempotency header when the sender has a stable delivery ID.
Keep provider-specific behavior in your reasoner, not in a fake named integration.

Source Surfaces

Generic HMAC

Generic Bearer

Dispatch Contract

Notes

On this page