---
title: "Create a new webhook subscription"
method: POST
path: "/self/webhooks"
tags: ["Webhooks"]
---

# Create a new webhook subscription

`POST /self/webhooks`

## Request body

- WebhookCreate
  - `events` string[] — Events to subscribe to the webhook
  - `metadataPolicy` 'NONE' | 'HEADER' | 'BODY' — Metadata policy for the webhook
  - `signingAlgo` 'HMAC_SHA256' — Signing algorithm for the webhook
  - `signingKey` string — Signing key for the webhook
  - `url` string — Destination URL for events

## Response `201`

Successful

- Webhook
  - `accountId` string — Unique identifier of the account
  - `createdAt` string — Created time for the webhook
  - `events` string[] — Subscribed events for the webhook
  - `expireAt` string — Expiration time for the webhook
  - `id` string — Unique identifier for the webhook
  - `metadataPolicy` 'NONE' | 'HEADER' | 'BODY' — Metadata policy for the webhook
  - `purgeAt` string — Scheduled purge time for the webhook
  - `renewedAt` string — Last renewed time for the webhook
  - `signingAlgo` 'HMAC_SHA256' | 'NONE' — Signing algorithm for the webhook
  - `signingKey` string — Signing key for the webhook
  - `statistics` object
    - `failed` boolean — Current delivery status
    - `totalAttempts` integer — Total delivery attempts
    - `totalFailures` integer — Total failed deliveries
    - `totalSuccesses` integer — Total successful deliveries
  - `status` 'ACTIVE' | 'PAUSED' — Status for the webhook
  - `url` string — Destination URL for events
  - `userId` string — Unique identifier of the user

## Other responses

- `400` — Bad Request: The client should not repeat the request without modifications
- `401` — Unauthorized: Invalid access token
- `403` — Forbidden: The user has no rights to access the resource(s)
- `408` — Timeout: The client may repeat the request without modifications
- `422` — Validation Error
- `500` — Internal Server Error
- `502` — Bad Gateway

---

[API](https://skmtc.net/vonage/apis/vgis.md) · [All operations](https://skmtc.net/vonage/apis/vgis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vonage/vgis/versions/343ef79f45ec/schema)