Create subscription

Owned by Helen Griffith
Last updated: Oct 11, 2023
2 min read


Beta/Early Access Program

This API is in the Beta/Early Access Program and is still under development. If you are interested in using this API, please contact your Customer Success Manager or Account Manager. Participation in this pilot program is at the discretion of Product Management and not guaranteed.

Use of this API outside of the program is prohibited.

The POST /subscriptions endpoint can be used to create a new subscription.

In this page


Most URLs in the example code use the following values:

Headers

Header parameters in Requests (Webhooks API) apply to this endpoint.

Authorization scopes required:

Scope
admin:write

Body

{
    "name": "WebhookTest1",
    "url": "https://your-application.com/abc/123",
    "events": [
        "agent.presencechanged.v0"
    ],
    "enabled": true,
    "secret": "OFd4WHqXISxMAgoYneiFhgdGrOgYeToYPN3HjIO4xAxDvWd/oIKTW1P4A6GLXN0McDGlLtnTn1KCGCa+W5Gu="
}

An object representing the new subscription should be sent in the body. The body must contain the following properties:

  • name — The name of the subscription. The name must be unique.
  • url — The URL that the webhook events are sent to. It must be a fully qualified http or https URL.
  • events — A list of the event types you wish to receive webhook notifications for. Each item in the list must be the name of an event type. You can get a list of event types to discover their names. You can subscribe to sets of event types using a wildcard.

The body may optionally contain these additional properties:

  • enabled — Notifications will only be sent to the URL if the subscription is enabled. If not specified, the subscription will be enabled when it is created.
  • secret — The secret used to sign notifications. If not specified, a secret will be automatically generated and returned in the response.

Requests

Creates a new subscription

curl -L -X POST "https://***.api.newvoicemedia.com/webhooks/subscriptions" \
-H "Authorization: bearer <ACCESS_TOKEN>" \
-H "Accept: application/vnd.newvoicemedia.v1+json"

Responses

The response returns the new value of the subscription.

Successful response

Success response code and parameters in Requests (Webhooks API) apply to a successful response.

The new subscription will be returned in the response.

Example response

{
    "subscriptionId": "2V1lVz6FeKOuVLEpSU6M0aqkM9b",
    "name": "WebhookTest1",
    "url": "https://your-application.com/webhooks/events",
    "events": [
        "agent.presencechanged.v0"
    ],
    "enabled": true,
    "secret": "OFd4WHqXISxMAgoYneiFhgdGrOgYeToYPN3HjIO4xAxDvWd/oIKTW1P4A6GLXN0McDGlLtnTn1KCGCa+W5Gu="
}

The subscription contains the following parameters:

  • subscriptionId — The unique identifier for the subscription. This ID can be used to edit or delete the subscription.
  • name — The name of the subscription, specified during creation. The name is unique.
  • url — The URL that the webhook events are sent to. It is a fully qualified http or https URL.
  • events — A list of the types of events subscribed to. Each item in the list is the name of an event type. Wildcards are used to subscribe to sets of event types.
  • enabled — Notifications are only sent to the URL if the subscription is enabled.
  • secret — A secret used to sign notifications. The current secret is not returned in API responses except when you create a subscription.

Try it out

  

For information, see Trying out Vonage Contact Center APIs.