InboxGuard Webhooks API

openapi: 3.2.0
info:
  title: InboxGuard Webhooks API
  version: 1.2.0
  summary: Email deliverability monitoring, DMARC reporting, and DNS authentication scanning.
  description: 'The InboxGuard REST API lets developers and AI agents run on-demand deliverability scans (SPF, DKIM, DMARC, MTA-STS, TLS-RPT, BIMI, and DNS blocklists), re-verify raw email headers, manage monitored domains, read DMARC aggregate reports, list alerts, and manage API keys.


    ## Authentication

    Authenticated endpoints accept an InboxGuard API key as a bearer token:


    ```

    Authorization: Bearer ig_live_xxxxxxxxxxxxxxxxxxxxxxxx

    ```


    Mint keys in the dashboard (Settings → API keys) or via `POST /api-keys`. Keys carry scopes: `read` (GET only) or `full` (all methods). See https://inboxguard.io/auth.md.


    ## Errors

    Every error returns the same structured envelope (`#/components/schemas/Error`): `{ "error": { "code": "RATE_LIMIT", "message": "...", "requestId": "..." } }`.


    ## Rate limits

    The anonymous `POST /scan-domain` endpoint allows 5 requests/hour per IP; authenticated callers get their plan''s hourly limit. `POST /scan-domain` responses carry `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (and `X-RateLimit-*` equivalents); 429 responses add `Retry-After`.


    ## Idempotency

    `POST /scan-domain` accepts an optional `Idempotency-Key` header with real replay semantics: a retry with the same key from the same caller within 1 hour returns the stored response instead of re-running the scan, marked with an `Idempotency-Replayed: true` response header.


    ## Versioning

    The API uses unversioned, stable URLs (one surface — no `/v1` path prefix). The current API version is echoed on every response in the `API-Version` header. Additive, backward-compatible changes (new endpoints, new optional fields) ship continuously without a version bump. Breaking changes — when they are ever needed — ship under a NEW version that you opt into by sending an optional `Accept-Version` request header; the existing behaviour remains the default so unversioned callers are never broken. Omit `Accept-Version` to always get the current stable version. Upcoming breaking changes are announced in these docs and at https://inboxguard.io/llms-full.txt in advance.


    ## Pagination

    Only `GET /scans` is paginated: pass `?before=` (from the previous response''s `nextCursor`) to walk older scans. `GET /domains`, `GET /alerts`, and `GET /api-keys` return the full (limit-capped) list in one response — there are no `cursor` parameters.'
  termsOfService: https://inboxguard.io/terms
  contact:
    name: InboxGuard Support
    email: support@inboxguard.io
    url: https://inboxguard.io/contact
  license:
    name: Proprietary
    url: https://inboxguard.io/terms
  x-deprecation-policy: 'Unversioned, stable URLs. When an endpoint or field is ever deprecated, responses carry a ''Deprecation: true'' header and a ''Sunset: <HTTP-date>'' header marking the removal date — at least 6 months out — plus a ''Link: <url>; rel="deprecation"'' pointer to migration notes. Opt into a future breaking version with the optional ''Accept-Version'' request header. Nothing is deprecated today.'
servers:
- url: https://api.inboxguard.io
  description: Production
security:
- ApiKeyBearer: []
tags:
- name: Webhooks
paths: {}
webhooks:
  alertEvent:
    post:
      tags:
      - Webhooks
      summary: Signed alert-event delivery (InboxGuard → your endpoint)
      operationId: alertEventWebhook
      description: 'When you configure a `webhook`, `slack`, or `teams` notification channel, InboxGuard POSTs each alert event to your URL as JSON. Every delivery is signed with HMAC-SHA256 (the same construction Stripe uses) so you can verify authenticity and guard against replay. The destination is re-validated against private/metadata IP ranges on every send (SSRF-safe) and redirects are never followed. Full verification guide + Node/Python code: https://inboxguard.io/webhooks.md.'
      security: []
      parameters:
      - name: X-InboxGuard-Signature
        in: header
        required: true
        schema:
          type: string
          example: t=1700000000,v1=4f1e9b2c…c9
        description: '`t=<unix-seconds>,v1=<hex>`, where v1 = HMAC-SHA256(channel signing_secret, `"<t>." + rawRequestBody`). Recompute over the RAW body bytes (do not re-serialize the parsed JSON) and compare constant-time.'
      - name: X-InboxGuard-Timestamp
        in: header
        required: true
        schema:
          type: string
          example: '1700000000'
        description: Unix seconds when the request was signed. Reject if more than ~300s from now (replay protection).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookAlertEvent'
      responses:
        '200':
          description: Acknowledged. Return any 2xx; a non-2xx response is recorded as a failed delivery.
components:
  schemas:
    WebhookAlertEvent:
      type: object
      description: Body of a signed alert-event webhook delivery. Verify the X-InboxGuard-Signature header before trusting it — see https://inboxguard.io/webhooks.md.
      required:
      - alertId
      - orgId
      - kind
      - severity
      - message
      properties:
        alertId:
          type: string
          format: uuid
        orgId:
          type: string
          format: uuid
        entityType:
          type: string
          enum:
          - domain
          example: domain
        entityId:
          type: string
          format: uuid
        kind:
          type: string
          example: blocklist.listed
          description: Event type, e.g. blocklist.listed, score.dropped, check.failed.
        severity:
          type: string
          enum:
          - info
          - warning
          - critical
          example: critical
        message:
          type: string
        details:
          type: object
          additionalProperties: true
          example:
            causes:
            - zen.spamhaus.org
        org:
          type: object
          properties:
            name:
              type: string
              example: Acme
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: InboxGuard API key (ig_live_… / ig_test_…)
      description: 'PRIMARY auth: send an InboxGuard API key as a bearer token (`Authorization: Bearer ig_live_…`). Scopes: `read` (GET) and `full` (all methods). Mint a key at https://inboxguard.io/settings or per https://inboxguard.io/auth.md.'
    OAuth2:
      type: oauth2
      description: 'OAuth-shaped wrapper around the same API key. The ONLY grant is client_credentials at POST https://api.inboxguard.io/oauth/token, where the client_secret IS an InboxGuard API key (HTTP Basic or body); the returned access_token is that same key. There is NO authorization_code flow, NO PKCE, and NO /oauth/authorize endpoint. Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource on api.inboxguard.io. See https://inboxguard.io/auth.md.'
      flows:
        clientCredentials:
          tokenUrl: https://api.inboxguard.io/oauth/token
          scopes:
            read: Read-only access (GET).
            full: Full read/write access (all methods).
externalDocs:
  description: API quickstart and guides
  url: https://inboxguard.io/guides/api-quickstart