> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mallary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook

> Create a webhook for post and auto-reply lifecycle events.

## Delivery body

Mallary sends a JSON body like this:

```json theme={null}
{
  "event": "post.published",
  "event_id": "7dd724b3-e237-4b1f-9d3c-28f1932eb195",
  "data": {
    "batch_id": "batch_example",
    "platform": "facebook",
    "status": "completed"
  },
  "sent_at": "2026-08-08T12:00:00.000Z",
  "signed_payload": "{\"event\":\"post.published\",\"event_id\":\"7dd724b3-e237-4b1f-9d3c-28f1932eb195\",\"data\":{\"batch_id\":\"batch_example\",\"platform\":\"facebook\",\"status\":\"completed\"},\"sent_at\":\"2026-08-08T12:00:00.000Z\"}"
}
```

If you set a webhook secret, Mallary sends `X-Mallary-Payload-Signature` as `sha256=<hex digest>`. It is the HMAC-SHA256 signature of the exact `signed_payload` string. Verify it before parsing or using the event.

## Final failures

Subscribe to `post.job_failed` for a job's final failure. This event is saved as soon as the job fails, even if other jobs in its batch are still waiting. It also works for jobs without a batch. A final failure has `retries_remaining: 0` and `retry_at: null`.

`post.failed`, `post.partial`, and `post.published` keep their existing batch behavior. For prompt failure alerts, use `post.job_failed`. Use `*` to receive all events, including the job events.

## Delivery retries

Mallary saves each delivery before sending it. A failed delivery gets up to five more attempts, with waits of 1 minute, 5 minutes, 30 minutes, 2 hours, and 8 hours. A valid `Retry-After` header can extend a wait, up to 24 hours. Each HTTP attempt has a 10-second timeout. Redirects count as failed deliveries.

The body, `event_id`, and `sent_at` stay the same across retries. `X-Mallary-Event-Id` also contains the event ID. Your endpoint should return a 2xx response and handle each event ID once: a lost response can cause the same event to arrive again. Keep the event ID for at least seven days.

Events can arrive out of order while a delivery is being retried. Read the job's current status before taking action on an older event.

Delivery retries send the notification again. They do not retry the social post. Deleting or disabling a webhook cancels its pending deliveries; a request already in flight may still finish.

Use [delivery history](https://docs.mallary.ai/api-reference/endpoint/webhooks-deliveries.md) to inspect each attempt and find deliveries that ran out of retries. These records start when durable delivery is enabled; earlier deliveries are not backfilled.


## OpenAPI

````yaml POST /api/v1/webhooks
openapi: 3.0.3
info:
  title: Mallary API
  version: 1.6.0
  description: >
    Public API for multi-platform publishing, analytics, media upload, and
    webhooks.


    Authentication:

    - Use header `Authorization: Bearer {api_key}`.

    - API key identity is authoritative. Do not use `user_id` to identify a
    caller.


    Connection profiles:

    - Omit `profile_id` to use the authenticated user's default profile.

    - Send the profile's random public `profile_id` when you want to publish,
    list posts, read post analytics or audience counts, list platforms, update
    settings, or disconnect a platform for a non-default profile.

    - Use `GET /api/v1/profiles` to list profile IDs.

    - Total social media accounts: Starter 5 ($15/month), Pro 15 ($29/month),
    Business 100 ($95/month). Posts are unlimited. Scheduling, analytics, and AI
    auto-replies are included. X publishing and comments use credits at cost;
    analytics and account lookups use no credits. Existing customers keep their
    current terms; use the authenticated workspace limits.


    Rate limits (per user, per minute) depend on subscription plan:

    - plan_id 1: 75 req/min

    - plan_id 2: 150 req/min

    - plan_id 3: 750 req/min

    - plan_id 4: 1500 req/min
servers:
  - url: https://mallary.ai
    description: Production
security:
  - bearerAuth: []
externalDocs:
  description: Full product docs
  url: https://docs.mallary.ai/
paths:
  /api/v1/webhooks:
    post:
      summary: Create webhook
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/WebhookEvent'
                secret:
                  type: string
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  url:
                    type: string
                    format: uri
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEvent'
        '400':
          description: Invalid request
        '401':
          description: Missing or invalid API key
components:
  schemas:
    WebhookEvent:
      type: string
      description: Use '*' to receive all events.
      enum:
        - '*'
        - post.scheduled
        - post.published
        - post.failed
        - post.partial
        - post.delayed
        - post.job_failed
        - auto_reply.posted
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer {api_key}`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.