Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Send reports to Slack, email, a webhook, or your own service

An alert channel is a destination for your reports. Once you add one, every analysis your account runs, in the web app or through one of your API keys, is delivered to it as soon as the run is complete and paid for: as JSON to any HTTPS endpoint, with your own headers and, if you want, your own body layout, or as an email to addresses that have confirmed they want it.

What a channel is

A channel is one of two things.

An HTTP channel is an HTTP destination. oculr sends one request per finished report to the URL you give, as POST (the default) or PUT, with the headers you add, and either the default payload or a body template of your own. Slack and Discord incoming webhooks, PagerDuty, Opsgenie, a Zapier or n8n trigger, or an endpoint on your own server all work the same way. Other methods are refused: a report is a body, and GET has none.

An email channel mails the report to up to 5 addresses. Your own sign-in address receives reports as soon as the channel exists. Any other address is mailed a confirmation link first and receives nothing until it is opened, so a channel can never be pointed at someone who did not ask. Every report mail carries an unsubscribe link; an address that uses it receives no further mail from any oculr account.

You can have up to 10 channels. Every enabled channel receives every report. There is no filtering by result today: a channel that should only hear about exploits is a filter on the receiving side, on the txType field.

Add a channel

  1. Sign in to oculr.xyz/app with Google or a wallet.
  2. Open the balance menu (top right) and choose Alert channels.
  3. Choose Add channel and pick the type.
    • HTTP request: give it a name, paste the URL, and add any headers the endpoint needs (an Authorization header, for example). Leave Default payload selected to receive the report as JSON, or choose Custom JSON template to shape the body for the receiver (see below).
    • Email: give it a name and list the recipients, one per line.
  4. Choose Add channel, then Send test on the new channel. The test delivers a sample payload marked "event": "test" (for email, a mail whose subject says it is a test) and shows what the endpoint or the mail provider answered: the HTTP status, the reason when nothing answered, and for an HTTP channel the first 1,024 characters of the endpoint's response body.

From then on, every report your account produces is sent to it. Pause a channel to stop deliveries without losing its configuration; delete it to remove it.

The URL must be https://. Addresses on private, loopback or link-local ranges are refused, whether written as an IP address or reached through a hostname that resolves to one.

Header values are write-only

An Authorization header is a credential. oculr treats every header value as a secret: it is stored encrypted (AES-256-GCM under a key that the storage never holds), used only to send with, and never shown again. The channel page shows the names of your headers, never their values. The URL is kept and shown in full: it is the destination you chose, and you can read it back and edit it at any time.

To change a header value, add it again with its new value (the page lets you remove the old one first; a header sent again under the same name replaces it). Nothing an API key can call returns a channel at all.

The default payload

With no template, the body is this JSON object:

{
  "event": "report.completed",
  "sentAt": "2026-11-08T12:00:00.000Z",
  "runId": 4815162342,
  "reportUrl": "https://mpp.oculr.xyz/runs/4815162342",
  "txHash": "0x...",
  "chain": "ethereum-mainnet",
  "chainId": 1,
  "chainName": "Ethereum",
  "explorerUrl": "https://etherscan.io/tx/0x...",
  "status": "success",
  "txType": "exploit",
  "protocol": "example_protocol",
  "confidence": "high",
  "usdValue": 1234567.89,
  "summary": "One paragraph on what the transaction did.",
  "risks": ["..."],
  "steps": ["..."],
  "findings": [
    {
      "broken_invariant": "...",
      "category": "...",
      "severity": "critical",
      "confidence": "high",
      "victim": [{ "address": "0x...", "kind": "contract" }],
      "attacker": [{ "address": "0x...", "kind": "wallet" }],
      "evidence": ["..."],
      "missing_data_to_confirm": []
    }
  ],
  "nonFindings": ["..."],
  "addresses": [{ "address": "0x...", "label": "...", "role": "..." }],
  "partial": false
}
FieldMeaning
eventreport.completed for a report, test for a test send.
runId, reportUrlThe run's id in your history and its full report over the API (GET /runs/{id}, which takes your API key). Both null when the run has no public id.
txHash, chain, chainId, chainName, explorerUrlThe transaction and the chain it was found on. The chain fields are null when no chain was detected.
statussuccess or reverted.
txType, protocol, confidence, usdValue, summary, risks, stepsThe same fields as the result. Route on txType; check confidence before trusting a summary verbatim.
findings, nonFindingsThe exploit triage: one finding per vulnerability, and what was considered and ruled out. Empty for non-exploit transactions.
addressesThe addresses the analysis labelled, with their roles.
partialtrue when an upstream source failed mid-run and the result is partial. Treat the summary as a lead, not a verdict.

The payload carries no cost figure and no trace: the report itself, with the trace, is at reportUrl.

Every request also carries X-Oculr-Event (the event value) and X-Oculr-Delivery, a unique id per delivery that a retry repeats, so a receiver can drop a duplicate.

Custom body templates

An HTTP channel's template is a JSON document in which {{placeholders}} name fields of the default payload. Keep it valid JSON: placeholders go inside string values. (An email channel's templates are Markdown, not JSON; see Email channels.)

A Slack incoming webhook, for example, wants {"text": "..."}:

{
  "text": "oculr: {{txType}} on {{chainName}} ({{confidence}} confidence)\n{{summary}}\n{{explorerUrl}}"
}

Two rules decide what a placeholder becomes:

  • Inside text, the field's value is spliced in. A string is inserted as it is; anything else (a number, a list) is inserted as JSON. A field that is missing or null becomes nothing.
  • A string that is only a placeholder takes the field's value as it is, with its type. "risks": "{{risks}}" makes risks a list, "usd": "{{usdValue}}" makes it a number, and "report": "{{report}}" embeds the whole default payload.

Paths use dots: {{findings.0.severity}} is the severity of the first finding. Keys are left as written; only values are filled.

The rendered body is always valid JSON whatever the summary contains (quotes, newlines, braces), because the template is filled as a parsed document and serialised again, never by text substitution.

A Discord webhook takes {"content": "..."}; a PagerDuty Events API v2 call takes a routing_key, event_action and a payload object, with your key in the body; any service that accepts JSON can be shaped the same way. If the receiver wants a different Content-Type, set it as a header: it replaces the default application/json.

Email channels

A report mail leads with the summary, rendered from the model's Markdown so headings, bullets, bold and code come through (the plain-text part keeps a blank line between sections), then the transaction, chain, type, confidence and USD value, the explorer and report links, the risks and the findings. Each recipient gets their own copy with their own unsubscribe link.

Subject and body templates

An email channel takes the same {{placeholders}} as an HTTP channel, in two places:

  • Subject. Every subject starts with oculr: ; what follows is yours. The default is <type> on <chain> (<confidence> confidence), with partial added for a partial result. A template such as {{txType}} hit {{protocol}} replaces that part only. The prefix stays whatever the template says, so one mail filter catches every alert.
  • Body. Markdown with placeholders replaces the default mail. A placeholder is filled as text: a string as it is, a number as written, a list ({{risks}}, {{steps}}) as one bullet per entry, {{findings}} as one bullet per finding ([severity] category: broken invariant), {{addresses}} as one bullet per address, and {{report}} as the whole payload in JSON. The result is rendered as Markdown, so your own headings, bullets and links are formatted too. The unsubscribe footer is appended to every mail whatever the template says.

A mail template is not JSON: write the text you want to read. Send test mails the sample payload through the templates, so the result can be checked before a real report arrives.

Recipients:

  • Your sign-in address (the Google account you use) is confirmed already and receives reports at once.
  • Any other address is mailed a confirmation link when you add it. The link opens a page with one button; the address is confirmed when the button is pressed, never by merely opening the link, so a mail scanner cannot confirm it. The link is valid for 24 hours; the channel page marks the address Pending until it is confirmed and offers Resend verification. Nothing is sent to a pending address. A confirmation is for your account only: another account that adds the same address asks again. One confirmation mail goes to an address per 10 minutes, and an account can send 20 a day.
  • An unsubscribed address never hears from oculr alerts again, from any account. The unsubscribe link opens a page with one button, and mail clients that support one-click unsubscribe can do it from their own interface. There is no way to re-subscribe it from the app.

Delivery

  • The request is made once your report is complete and its charge has been taken, so a channel never receives a report before you do. It does not delay or change what you see in the app or receive from the API. A run that stops with its charge incomplete is delivered to your channels when it is unlocked from your balance.
  • An HTTP endpoint has 10 seconds to answer. A 2xx answer is a delivery. A network failure or a 5xx is retried once, with the same X-Oculr-Delivery id. A 4xx is the endpoint's answer and is not retried. Redirects are not followed.
  • On a report delivery the response body is never read; only the status code is recorded. A test send from the page also records the first 1,024 characters of what the endpoint answered, so its error message (a Slack invalid_token, for example) is visible next to the status.
  • A mail is handed to the mail provider with the same single retry; the status recorded is the provider's answer.
  • The channel page shows the newest outcome for each channel: when it was, whether it was delivered, and the status or the reason it failed.

What a channel cannot do

A channel sends; it never reads. Nothing a receiving endpoint answers changes anything on your account. Channels are managed only while you are signed in to the web app: an API key cannot list, add or change them, and nothing returns a stored header value to anyone.

Related