App Webhooks API Reference

Last updated March 10, 2023

Webhook
Delivery
Event

Read App Webhooks for an overview of the functionality provided by this API.

Webhook

Represents the details of a webhook subscription.

Attributes

Name	Type	Description	Example
created_at	date-time	When the webhook was created.	`"2015-01-01T12:00:00Z"`
id	uuid	The webhook’s unique identifier.	`"01234567-89ab-cdef-0123-456789abcdef"`
include	array	The entities that the subscription provides notifications for.	`["api:release"]`
level	string	Either `notify` or `sync`. If `notify`, Heroku makes a single, fire-and-forget delivery attempt. If `sync`, Heroku attempts multiple deliveries until the request is successful or a limit is reached.	`"notify"`
updated_at	date-time	When the webhook was most recently updated.	`"2015-01-01T12:00:00Z"`
url	uri	The URL where the webhook’s notification requests are sent.	`http://example.com`

Webhook Create

Creates a webhook subscription for a particular app.

POST /apps/{app_id_or_name}/webhooks

Required Parameters

Name	Type	Description	Example
include	array	One or more entities that the subscription will provide event notifications for.	`["api:release"]`
level	string	Either `notify` or `sync`. If `notify`, Heroku makes a single, fire-and-forget delivery attempt. If `sync`, Heroku attempts multiple deliveries until the request is successful or a limit is reached.	`"notify"`
url	uri	The URL where the webhook’s notification requests are sent.	`http://example.com`

Optional Parameters

Name	Type	Description	Example
authorization	nullable string	A custom `Authorization` header that Heroku will include with all webhook notifications.	`"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3"`
secret	nullable string	A value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s `Heroku-Webhook-Hmac-SHA256` header). If you omit this value, a generated secret is returned by the API. This value can never be retrieved again, so you must persist it immediately. If you don’t, you can run `heroku webhooks:update` to refresh the secret at a later time.	`"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad"`

Curl Example

$ curl -n -X POST https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks \
  -d '{
  "authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
  "url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 201 Created
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Webhook Delete

Removes an app webhook subscription.

DELETE /apps/{app_id_or_name}/webhooks/{webhook_id}

Curl Example

$ curl -n -X DELETE https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$WEBHOOK_ID \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Webhook Info

Returns the info for an app webhook subscription.

GET /apps/{app_id_or_name}/webhooks/{webhook_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$WEBHOOK_ID \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Webhook List

List all webhook subscriptions for a particular app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/webhooks

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

[
  {
    "app": {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "name": "example"
    },
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": [
      "api:release"
    ],
    "level": "notify",
    "updated_at": "2015-01-01T12:00:00Z",
    "url": "example"
  }
]

Webhook Update

Updates the details of an app webhook subscription.

PATCH /apps/{app_id_or_name}/webhooks/{webhook_id}

Optional Parameters

Name	Type	Description	Example
authorization	nullable string	A custom `Authorization` header that Heroku will include with all webhook notifications.	`"Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3"`
include	array	The entities that the subscription provides notifications for.	`["api:release"]`
level	string	Either `notify` or `sync`. If `notify`, Heroku makes a single, fire-and-forget delivery attempt. If `sync`, Heroku attempts multiple deliveries until the request is successful or a limit is reached.	`"notify"`
secret	nullable string	A value that Heroku will use to sign all webhook notification requests (the signature is included in the request’s `Heroku-Webhook-Hmac-SHA256` header). If you omit this value, a generated secret is returned by the API. This value can never be retrieved again, so you must persist it immediately. If you don’t, you can run `heroku webhooks:update` to refresh the secret at a later time.	`"dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad"`
url	uri	The URL where the webhook’s notification requests are sent.	`http://example.com`

Curl Example

$ curl -n -X PATCH https://api.heroku.com/apps/$APP_ID_OR_NAME/webhooks/$WEBHOOK_ID \
  -d '{
  "authorization": "Bearer 9266671b2767f804c9d5809c2d384ed57d8f8ce1abd1043e1fb3fbbcb8c3",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "secret": "dcbff0c4430a2960a2552389d587bc58d30a37a8cf3f75f8fb77abe667ad",
  "url": "example"
}' \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "app": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "name": "example"
  },
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": [
    "api:release"
  ],
  "level": "notify",
  "updated_at": "2015-01-01T12:00:00Z",
  "url": "example"
}

Delivery

Stability: production

Represents the delivery of a webhook notification, including its current status.

Attributes

Name	Type	Description	Example
created_at	date-time	When the delivery entity was created.	`"2015-01-01T12:00:00Z"`
event:id	uuid	The unique identifier of the delivery’s associated webhook event.	`"01234567-89ab-cdef-0123-456789abcdef"`
event:include	string	include that matches with webhooks	`"api:release"`
id	uuid	The delivery’s unique identifier.	`"01234567-89ab-cdef-0123-456789abcdef"`
last_attempt	nullable object	last attempt of a delivery	`null`
last_attempt:code	nullable integer	http response code received during attempt	`null`
last_attempt:created_at	date-time	when attempt was created	`"2015-01-01T12:00:00Z"`
last_attempt:error_class	nullable string	error class encountered during attempt	`null`
last_attempt:id	uuid	unique identifier of attempt	`"01234567-89ab-cdef-0123-456789abcdef"`
last_attempt:status	string	status of an attempt one of:`"scheduled"` or `"succeeded"` or `"failed"`	`"scheduled"`
last_attempt:updated_at	date-time	when attempt was updated	`"2015-01-01T12:00:00Z"`
next_attempt_at	nullable date-time	when delivery will be attempted again	`null`
num_attempts	integer	number of times a delivery has been attempted	`42`
status	string	The delivery’s status (one of `"pending"` or `"scheduled"` or `"retrying"` or `"failed"` or `"succeeded"`).	`"pending"`
updated_at	date-time	When the delivery entity was last updated.	`"2015-01-01T12:00:00Z"`
webhook:id	uuid	The unique identifier of the delivery’s associated webhook subscription.	`"01234567-89ab-cdef-0123-456789abcdef"`
webhook:level	string	delivery behavior. “notify” provides a single, fire-and-forget delivery attempt; while “sync” attempts multiple deliveries until successful or timed out one of:`"notify"` or `"sync"`	`"notify"`

Delivery Info

Returns the info for an existing delivery entity.

GET /apps/{app_id_or_name}/webhook-deliveries/{delivery_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-deliveries/$DELIVERY_ID \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "created_at": "2015-01-01T12:00:00Z",
  "event": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  },
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "pending",
  "updated_at": "2015-01-01T12:00:00Z",
  "webhook": {
    "id": "01234567-89ab-cdef-0123-456789abcdef"
  }
}

Delivery List

Lists existing deliveries for an app.

The only acceptable order value for the Range header is id. This endpoint only lists deliveries from the past 7 days with a maximum of 300 records per webhook.

GET /apps/{app_id_or_name}/webhook-deliveries

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-deliveries \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "event": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "status": "pending",
    "updated_at": "2015-01-01T12:00:00Z",
    "webhook": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
]

Event

Stability: production

Represents a webhook event that occurred.

Attributes

Name	Type	Description	Example
created_at	date-time	When the event entity was created.	`"2015-01-01T12:00:00Z"`
id	uuid	The event’s unique identifier.	`"01234567-89ab-cdef-0123-456789abcdef"`
include	string	The type of entity that the event is related to.	`"api:release"`
payload:action	string	The type of event that occurred	`"create"`
payload:actor:email	email	The email address of the Heroku user that initiated the event.	`"username@example.com"`
payload:actor:id	uuid	The unique identifier of the Heroku user that initiated the event.	`"01234567-89ab-cdef-0123-456789abcdef"`
payload:data	object	The current details of the event.
payload:previous_data	object	Previous details of the event (if any).
payload:resource	string	The type of resource associated with the event.	`"release"`
payload:version	string	The version of the details provided for the event.	`"1"`
updated_at	date-time	When the event was last updated.	`"2015-01-01T12:00:00Z"`

Event Info

Returns the info for a specified webhook event.

GET /apps/{app_id_or_name}/webhook-events/{webhook_id}

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-events/$WEBHOOK_ID \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

{
  "created_at": "2015-01-01T12:00:00Z",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "include": "api:release",
  "payload": {
    "action": "create",
    "actor": {
      "email": "username@example.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    "data": null,
    "previous_data": null,
    "resource": "release",
    "version": "1"
  },
  "updated_at": "2015-01-01T12:00:00Z"
}

Event List

Lists existing webhook events for an app.

The only acceptable order value for the Range header is id.

GET /apps/{app_id_or_name}/webhook-events

Curl Example

$ curl -n https://api.heroku.com/apps/$APP_ID_OR_NAME/webhook-events \
  -H "Accept: application/vnd.heroku+json; version=3.webhooks"

Response Example

HTTP/1.1 200 OK
Accept-Ranges: id
Content-Range: id 01234567-89ab-cdef-0123-456789abcdef..01234567-89ab-cdef-0123-456789abcdef; max=200
ETag: "0123456789abcdef0123456789abcdef"
Last-Modified: Sun, 01 Jan 2012 12:00:00 GMT
RateLimit-Remaining: 2400

[
  {
    "created_at": "2015-01-01T12:00:00Z",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "include": "api:release",
    "payload": {
      "action": "create",
      "actor": {
        "email": "username@example.com",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      },
      "data": null,
      "previous_data": null,
      "resource": "release",
      "version": "1"
    },
    "updated_at": "2015-01-01T12:00:00Z"
  }
]

Keep reading

App Webhooks

Categories

App Webhooks API Reference

Table of Contents

Webhook

Attributes

Webhook Create

Required Parameters

Optional Parameters

Curl Example

Response Example

Webhook Delete

Curl Example

Response Example

Webhook Info

Curl Example

Response Example

Webhook List

Curl Example

Response Example

Webhook Update

Optional Parameters

Curl Example

Response Example

Delivery

Attributes

Delivery Info

Curl Example

Response Example

Delivery List

Curl Example

Response Example

Event

Attributes

Event Info

Curl Example

Response Example

Event List

Curl Example

Response Example

Keep reading

Feedback