Webhook consumers

A webhook consumer receives ShoulderTap’s events as HTTP POSTs. This is the standard way to integrate a consumer that runs as its own service: you register a URL, and ShoulderTap POSTs to it whenever something happens to one of your requests.

Register

curl -X POST http://localhost:8776/api/v1/consumers \
  -H "Authorization: Bearer $SHOULDERTAP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-consumer",
    "handles_kinds": ["glossary.definition", "freeform.answer"],
    "delivery": {"type": "webhook", "url": "https://my-service.example.com/shouldertap-webhook"},
    "dedup_window": "PT24H"
  }'

See the Consumers endpoint for every registration field, including auto_accept and custom kind_schemas.

Event payloads

Each POST body has an event field naming what happened, plus the relevant data:

{
  "event": "proposal_accepted",
  "proposal": { "...ContextProposal..." }
}

{
  "event": "proposal",
  "proposal": { "...ContextProposal..." }
}

{
  "event": "proposal_rejected",
  "proposal": { "...ContextProposal..." },
  "reason": "not accurate"
}

{
  "event": "request_failed",
  "request_id": "req_01J...",
  "reason": { "code": "timeout" }
}

The one that matters is proposal_accepted — that’s when a human has approved the answer and you should write it to your system of record. The proposal object carries the expert’s verbatim answer, the LLM-structured form, and provenance. See the ContextProposal contract.

Handle the webhook

A minimal handler validates the payload and acts only on acceptance:

from fastapi import FastAPI, Request
from shouldertap.engine.contracts import ContextProposal

app = FastAPI()

@app.post("/shouldertap-webhook")
async def webhook(request: Request):
    payload = await request.json()
    if payload.get("event") != "proposal_accepted":
        return {"ignored": True}
    proposal = ContextProposal.model_validate(payload["proposal"])
    # write proposal.structured (or proposal.answer) to your system of record
    return {"ok": True}

ContextProposal does not carry the original request’s context. If your write-back needs to know which entity a request mapped to (for example, which glossary term to update), track that mapping on the consumer side, keyed by request_id. The examples/openmetadata_sync/ consumer in the repository shows this pattern with a small /remember endpoint.

Write-back adapters

Rather than writing the delivery-to-system-of-record logic yourself, you can use a built-in adapter that turns an accepted proposal into a write against OpenMetadata or any webhook target. See Write-back adapters.

Get started

Run the engine

Integrate agents

Reference

Register

Event payloads

Handle the webhook

Write-back adapters

​Register

​Event payloads

​Handle the webhook

​Write-back adapters

Register

Event payloads

Handle the webhook

Write-back adapters