> ## Documentation Index > Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt > Use this file to discover all available pages before exploring further. # Post webhooks ## OpenAPI ````yaml /openapi.json post /webhooks openapi: 3.1.1 info: title: Anima API version: 0.1.0 description: >- The Anima API provides programmatic access to unified infrastructure for AI agents: create and manage agents; send and receive email; place phone calls and send/receive SMS and voice; store and retrieve vault credentials; manage agent identity; and configure webhooks for real-time events. Authenticate using a Bearer token or an API key passed via the X-API-Key header. contact: name: Anima Labs url: https://useanima.sh email: support@useanima.sh license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: https://api.useanima.sh/v1 description: Production security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: Agents description: Create and manage AI agents with email and phone capabilities - name: Inboxes description: Manage email inboxes and their configurations - name: Messages description: Send, receive, and search email messages - name: Webhooks description: Register and manage webhook subscriptions for real-time events - name: Organizations description: Manage organizations and team settings - name: Domains description: Configure and verify custom email domains - name: Phone description: Manage phone numbers and SMS/voice capabilities - name: Invoices description: Track invoices, match receipts, and reconcile payments - name: Billing description: View usage, tiers, and billing information - name: Security description: Configure security policies and access controls - name: Vault description: Store and retrieve encrypted secrets - name: API Keys description: Create and manage API keys for programmatic access paths: /webhooks: post: operationId: webhook.create requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: HTTPS endpoint URL that will receive webhook POST payloads events: type: array items: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9*]+(\.[a-z0-9*]+)*$ description: >- Event name or glob pattern. Examples: 'email.received', 'email.*', 'call.ended', '*'. description: List of event types this webhook subscribes to description: type: string description: Optional human-readable label for this webhook active: default: true type: boolean description: Whether the webhook is active and receiving events authConfig: anyOf: - type: object properties: type: const: none required: - type description: >- No customer auth header (the HMAC signature is still sent) - type: object properties: type: const: bearer token: type: string minLength: 1 maxLength: 4096 description: 'Sent as `Authorization: Bearer `' required: - type - token - type: object properties: type: const: basic username: type: string minLength: 1 maxLength: 256 password: type: string minLength: 1 maxLength: 1024 required: - type - username - password description: >- Sent as `Authorization: Basic ` - type: object properties: type: const: custom_header headerName: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+$ value: type: string minLength: 1 maxLength: 4096 required: - type - headerName - value description: 'Sent as a custom header `: `' description: >- Auth the platform presents to your endpoint (in addition to the HMAC signature) rateLimitPerMinute: type: integer minimum: 0 maximum: 100000 description: >- Max deliveries per minute to this endpoint; omit for unlimited maxAttempts: type: integer minimum: 1 maximum: 10 description: Max delivery attempts before dead-lettering (default 3) required: - url - events description: Request body for creating a new webhook subscription responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string pattern: ^[0-9a-z]+$ description: Unique identifier for the webhook orgId: type: string pattern: ^[0-9a-z]+$ description: Organization that owns this webhook url: type: string format: uri description: HTTPS endpoint URL receiving webhook payloads events: type: array items: type: string minLength: 1 maxLength: 100 pattern: ^[a-z0-9*]+(\.[a-z0-9*]+)*$ description: >- Event name or glob pattern. Examples: 'email.received', 'email.*', 'call.ended', '*'. description: Event types this webhook is subscribed to active: type: boolean description: Whether the webhook is currently active description: anyOf: - type: string - type: 'null' description: Human-readable label for this webhook consecutiveFailures: type: integer minimum: 0 description: Number of consecutive delivery failures across all events disabledReason: anyOf: - type: string - type: 'null' description: >- Reason the webhook was auto-disabled, null if manually disabled or active disabledAt: anyOf: - type: string format: date-time - type: 'null' description: ISO 8601 timestamp when the webhook was auto-disabled createdAt: type: string format: date-time description: ISO 8601 timestamp when the webhook was created updatedAt: type: string format: date-time description: ISO 8601 timestamp when the webhook was last modified authType: enum: - NONE - BEARER - BASIC - CUSTOM_HEADER type: string description: >- Auth scheme the platform presents to your endpoint (never includes the secret) authHeaderName: anyOf: - type: string - type: 'null' description: Header name for CUSTOM_HEADER auth; null for other schemes rateLimitPerMinute: anyOf: - type: integer - type: 'null' description: >- Per-endpoint delivery rate cap in requests/minute; null = unlimited maxAttempts: anyOf: - type: integer - type: 'null' description: >- Per-webhook max delivery attempts; null = platform default (3) secret: type: string description: >- The signing secret, returned ONLY at creation time. Store it now — read endpoints (get/list) never return it again. Use it to verify the X-Anima-Signature header on every delivery. If lost, rotate via POST /webhooks/{id}/rotate-secret. required: - id - orgId - url - events - active - description - consecutiveFailures - disabledReason - disabledAt - createdAt - updatedAt - authType - authHeaderName - rateLimitPerMinute - maxAttempts - secret description: Newly created webhook, including its one-time signing secret components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'API key for programmatic access. Pass as: X-API-Key: ' ````