App Webhooks API Reference

Table of Contents [expand]

Last updated March 10, 2023

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

Webhook

Stability: production

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"
  }
]