---
title: "Webhook Subscribe"
method: POST
path: "/api/v1/webhooks/subscriptions"
---

# Webhook Subscribe

`POST /api/v1/webhooks/subscriptions`

## Request

- Base URL: `https://api.mesharc.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mesharc.dev/api/v1/webhooks/subscriptions`
- Auth: none declared

Send a project's events to one more URL, beside its own webhook.

For apps that turn a project's events into their own triggers: a zap
or a workflow subscribes when it is switched on and deletes its
subscription when it is switched off. Each subscription has a secret
of its own (`subscription.secret`, here only): its messages are signed
with it, as `X-MeshArc-Signature`, exactly as the project's own are
with the project's. Subscribing the same URL to the same project again
returns that subscription (200, `created: false`) with the events now
named. 400 on a URL that is not public http(s) or an event the project
does not send; 409 when the project has 25 already.

## Headers

- `authorization` string, nullable
- `x-mesharc-tenant` string, nullable

## Request body

- SubscriptionCreate
  - `projectId` string, required
  - `url` string, required
  - `events` string[], nullable
  - `label` string, nullable

## Response `201`

Successful Response

- SubscriptionCreated
  - `subscription` Subscription, required
    - `id` string, required
    - `projectId` string, required
    - `url` string, required
    - `events` string[], required
    - `label` string
    - `createdAt` string, nullable
    - `secret` string, nullable
  - `created` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mesharc/apis/mesharc-api.md) · [All operations](https://skmtc.dev/mesharc/apis/mesharc-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mesharc/apis/mesharc-api/revisions/d63cc02dfec2?raw)