Skip to content

Create Webhook Subscription
Alpha

Request

Create a new webhook subscription to receive event notifications at the specified URL.

Security
OAuth2(Required scopes: webhook.write)
Bodyapplication/jsonrequired
urlstringrequired

The URL to send webhook events to.

event_typesArray of strings, non-emptyrequired

List of event types to subscribe to. At least one event type must be specified.

statestringrequired

The state of the subscription.

Default:"ENABLED"
Enum:"ENABLED""DISABLED"
metadataobject

Additional metadata for the subscription.

This property lets you add custom data to the subscription. The key has a limit of 40 characters and the value has a limit of 500 characters.

curl -i -X POST \
  https://api.understory.io/v1/webhook-subscriptions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "string",
    "event_types": [
      "string"
    ],
    "state": "ENABLED",
    "metadata": {
      "property1": "string",
      "property2": "string"
    }
  }'

Responses

Subscription successfully created.

Bodyapplication/json
created_atstring, (date-time)required

Timestamp of when the subscription was created.

event_typesArray of stringsrequired

List of event types this subscription is subscribed to.

idstringrequired

The unique identifier of the subscription.

secretstringrequired

The secret key for verifying webhook signatures.

This value is only returned once when the subscription is created. Store it securely as it cannot be retrieved again.

statestringrequired

Whether the subscription currently delivers events.

  • ENABLED — events are delivered to the subscription's URL.
  • DISABLED — events are not delivered; the subscription is paused.
Enum:"ENABLED""DISABLED"
updated_atstring, (date-time)required

Timestamp of when the subscription was last updated.

urlstringrequired

The URL to send webhook events to.

metadataobject

Additional metadata for the subscription.

This property lets you add custom data to the subscription. The key has a limit of 40 characters and the value has a limit of 500 characters.

Response
{
  "id": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "state": "ENABLED",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "secret": "string"
}