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

# Create Webhook Subscription

> Subscribe a URL to one event type (REST hook)

# Create Webhook Subscription

Subscribes an HTTPS URL to one event type. From then on, every matching event is POSTed to that URL as a signed JSON envelope (see [Webhooks](/webhooks#webhook-subscriptions)). This is the endpoint Zapier, Make, n8n and similar tools call when a user turns on an automation; remove the subscription with [Delete Webhook Subscription](/api-reference/webhooks/delete-webhook) when it is turned off.

The key needs the **read** scope of the data the event carries: `attendees:read` for `attendee.registered`, `applications:read` for `form_response.created` and `form_response.updated`. A subscription stops delivering if its key is revoked.

## Body

<ParamField body="url" type="string" required>
  Where to deliver events. Must be a publicly reachable `https://` URL. Private and internal addresses are refused.
</ParamField>

<ParamField body="event" type="string" required>
  One of `attendee.registered`, `form_response.created`, `form_response.updated`.
</ParamField>

<ParamField body="event_id" type="string">
  `attendee.registered` only. Deliver registrations for this event alone. Omit for every event in the organization.
</ParamField>

<ParamField body="form_id" type="string">
  `form_response.created` and `form_response.updated` only. Deliver responses to this form alone. Omit for every form.
</ParamField>

## Response

Returns `201 Created`.

<ResponseField name="data" type="object">
  <Expandable title="Subscription object">
    <ResponseField name="id" type="string">Subscription identifier (`whk_...`). Use it to unsubscribe.</ResponseField>
    <ResponseField name="url" type="string">The delivery URL</ResponseField>
    <ResponseField name="event" type="string">The event type</ResponseField>
    <ResponseField name="event_id" type="string | null">Event filter</ResponseField>
    <ResponseField name="form_id" type="string | null">Form filter</ResponseField>
    <ResponseField name="status" type="string">`active`</ResponseField>
    <ResponseField name="source" type="string">`zapier` or `api`</ResponseField>
    <ResponseField name="last_delivered_at" type="string | null">Last successful delivery</ResponseField>
    <ResponseField name="last_failed_at" type="string | null">Last failed delivery</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp</ResponseField>

    <ResponseField name="secret" type="string">
      Signing secret (`whsec_...`) for verifying the `Gomry-Signature` header. Returned only in this response: store it now.
    </ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Status | `error` | When |
| - | - | - |
| 400 | `validation_error` | Missing or invalid field, a URL that is not public HTTPS, or a filter the event type does not support |
| 403 | `insufficient_scope` | The key lacks the read scope the event needs (`required_scope` names it) |
| 404 | `not_found` | `event_id` or `form_id` is not in your organization |
| 422 | `subscription_limit_reached` | The organization already has 100 active subscriptions |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://www.gomry.com/api/v1/webhooks" \
    -H "X-API-KEY: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/webhooks/gomry",
      "event": "attendee.registered"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "whk_3f9a1c2b4d5e6f708192a3b4",
      "url": "https://example.com/webhooks/gomry",
      "event": "attendee.registered",
      "event_id": null,
      "form_id": null,
      "status": "active",
      "source": "api",
      "last_delivered_at": null,
      "last_failed_at": null,
      "created_at": "2026-10-15T10:00:00.000Z",
      "secret": "whsec_Q2hhbmdlTWVJbkRvY3NFeGFtcGxlT25seUFiY2RlZg"
    }
  }
  ```
</ResponseExample>


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