Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Node.js Behavior in Heroku
      • Troubleshooting Node.js Apps
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
    • Heroku Inference
      • Inference API
      • Quick Start Guides
      • AI Models
      • Inference Essentials
    • Vector Database
    • Model Context Protocol
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • App Webhooks
  • App Webhooks API Reference

App Webhooks API Reference

English — 日本語に切り替える

Last updated March 10, 2023

Table of Contents

  • Webhook
  • Delivery
  • Event

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

Keep reading

  • App Webhooks

Feedback

Log in to submit feedback.

Webhook Dyno Events App Webhooks Tutorial

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices