Incoming webhooks (Phase 2)

Status

Incoming webhooks are planned for Phase 2 of the integrations roadmap. They are not available today. This page documents the design so you can plan integrations against it.

If you need this earlier, vote it up on /roadmap — high-priority items move faster.

What incoming webhooks will do

The reverse of generic outbound webhooks: an external system POSTs to a URL we expose, and the payload triggers an action inside AI Domination.

Planned triggers:

• External brand mention. Your PR tool detects a new article citing your brand; POST it to our webhook to add it to your mentions inbox.
• External audit signal. A vulnerability scanner or SEO tool flags an issue; POST it to seed an audit recommendation.
• External draft import. Your editorial calendar tool POSTs a brief; we generate a draft against it.

Planned shape

POST https://api.aidomination.app/v1/inbound/{endpoint-token}
Authorization: Bearer <signed token, time-limited>
Content-Type: application/json

{
  "type": "mention.create",
  "data": {
    "url": "https://example.com/article",
    "title": "Article title",
    "publishedAt": "2026-05-12T10:00:00Z",
    "sentiment": "positive"
  }
}

The endpoint token will be workspace-scoped, rotatable, and revocable, just like API keys.

Planned authentication

Two-factor: a workspace-bound endpoint token in the URL, plus a per-request bearer token signed with a shared secret. Verifying both blocks unauthorised callers even if the URL leaks.

Planned event handling

Each accepted event will:

1. Validate against the event-specific JSON schema.
2. Run rate-limit and quota checks.
3. Apply the action (create mention, seed draft, etc.).
4. Log to the audit trail with source=inbound-webhook and the inbound payload id for traceability.

Why not just use the API?

Three reasons we plan webhooks alongside the API:

1. Push vs. pull semantics. Many third-party tools support pushing events but not polling for them.
2. Signature verification by us. External tools sign their payloads; we verify on receipt and drop forged events. With an API call, the external tool needs an API key, which is a higher-value secret than a webhook signing key.
3. Rate-limit isolation. Inbound webhook quotas can be scaled independently of the read-API rate limit.

Until then

If you have an integration that would benefit from incoming events, two interim options:

1. Use Zapier or Make. Both can listen for events in your external tool and call our outbound API to mutate state.
2. Email forwarding. For mention-style ingestion, our support workflow accepts forwarded emails as a low-fi alternative. Email mentions@your-workspace.aidomination.app (per-workspace alias). Email-based ingestion is best-effort and not a long-term substitute.

Roadmap

Watch the roadmap page for the in-progress milestone. We'll update this doc with the real URL, scope semantics, and example payloads when implementation lands.