What request body formats can I POST to a webhook source, and how do I check my label mapping before going live?

Tares accepts one JSON object, a list of objects or NDJSON POSTed to the source’s ingest URL, and it stores the payload lossless. To check your label mapping before going live, run test_source with a sample payload, or POST a test and read Recent events and Fields. Fields shows which payload fields arrive and how often.

How it works

A webhook source is the catch-all connector for anything that can send an HTTP request: CI systems, GitHub webhooks, cron jobs and your own services. Each source has its own ingest URL, which ends in /ingest/ followed by the source’s ingest key.

• Body formats. Producers POST JSON as one object, a list, or NDJSON.
• Lossless storage. Tares keeps the full payload as it arrived. Labels do not filter it. They map the payload fields you care about into the event envelope so you can correlate on them.
• Labels. You declare one label per payload field you want to correlate on and mark one of them primary.
• Optional settings. event_type sets a fixed event type (the default is webhook_event). event_type_field reads the event type from a payload field such as action. text_template renders a line of text from payload fields. event_time_field names the payload field that holds an ISO-8601 event timestamp.

The full field reference is on the webhook connector page.

Set it up

1. Create the source. Ask a connected agent, for example: “Use tares to create a webhook source for my CI events, keyed by the payload’s pipeline field.” The agent calls create_source and returns the ingest URL. You can also go to Sources → Add source → webhook in the console, or send POST /api/sources with the same object. The response includes the ingest_key.

2. Declare the labels. This source reads the event type from action, renders text from action and sender, and labels each event by pipeline:

- name: ci-events
  connector: webhook
  config:
    event_type_field: action
    text_template: '{action} by {sender}'
    labels:
      - { name: pipeline, field: pipeline, primary: true }

3. Check the mapping first. Ask your agent to run test_source with a sample payload. It shows how your labels map before any real traffic arrives.

4. POST a test payload to the ingest URL:

curl -X POST http://localhost:8787/ingest/<ingest_key> \
  -H 'Content-Type: application/json' \
  -d '{"action": "deploy", "sender": "ci", "pipeline": "web"}'

5. Open the source page and read Recent events to see what Tares stored. Then open Fields to see which payload fields arrive and how often. Use that to pick a reliable key for your primary label. A field that shows up in every event is a better key than one that appears now and then.

6. Point your real producer at the ingest URL. When Tares has auth on, the sender uses a Bearer Authorization header holding an ingest-scoped API key. Creating a push source in the console mints one for it and shows it once. Without auth, no header is needed.

What you get

• A single ingest URL that takes one object, a list or NDJSON, so you do not reshape a producer’s output before sending it.
• Every payload stored lossless, so fields you did not label are still there.
• A way to confirm your label mapping with test_source before you go live.
• A real-traffic check in Recent events and Fields, which shows how often each payload field arrives so you can choose a dependable primary label.

Once events flow, they feed the correlation and escalation workflows described in AI SRE.

When something else fits

• If the sender is Prometheus Alertmanager, OpenTelemetry or Vercel, use the matching connector instead of a plain webhook source.
• If you want Tares to pull from a JSON endpoint on a schedule rather than receive posts, use the http_poll connector.

Related