Commerce webhooks

You can configure Commerce webhooks in your Cloud project with the ENABLE_WEBHOOKS global variable. Commerce webhooks send requests to an external server in response to Commerce-generated events. The Webhooks Guide describes this feature in detail.

Generic webhooks

You can capture and report Cloud infrastructure and repository events using a custom webhook integration to POST JSON messages to a webhook URL.

To add a webhook URL, use the following syntax:

magento-cloud integration:add --type=webhook --url=https://hook-url.example.com
  • type—Specify the webhook integration type.
  • url—Provide the webhook URL that can receive JSON messages.

The sample response shows a series of prompts that provide an opportunity to customize the integration. Using the default (blank) response sends messages about all events on all environments in a project.

You can customize the integration to report specific events, such as pushing code to a branch. For example, you can specify the environment.push event to send a message when a user pushes code to a branch:

Events to report (--events)
A list of events to report, e.g. environment.push
Default: *
Enter comma-separated values (or leave this blank)
>

You can choose to report events in a pending, in_progress, or complete state:

States to report (--states)
A list of states to report, e.g. pending, in_progress, complete
Default: complete
Enter comma-separated values (or leave this blank)
>

And you can include or exclude messages for specific environments:

Included environments (--environments)
The environment IDs to include
Default: *
Enter comma-separated values (or leave this blank)
>

Excluded environments (--excluded-environments)
The environment IDs to exclude
Enter comma-separated values (or leave this blank)
>

When the integration is complete, you receive a summary of the values:

Created integration integration-ID (type: webhook)
+-----------------------+------------------------------+
| Property              | Value                        |
+-----------------------+------------------------------+
| id                    | integration-ID               |
| type                  | webhook                      |
| events                | - '*'                        |
| environments          | - '*'                        |
| excluded_environments | {  }                         |
| states                | - complete                   |
| url                   | https://hook-url.example.com |
+-----------------------+------------------------------+

Update existing integration

You can update an existing integration. For example, change the states from complete to pending using the following:

magento-cloud integration:update --states=pending <int-id>

Sample response:

Integration integration-ID (webhook) updated
+-----------------------+------------------------------+
| Property              | Value                        |
+-----------------------+------------------------------+
| id                    | integration-ID               |
| type                  | webhook                      |
| events                | - '*'                        |
| environments          | - '*'                        |
| excluded_environments | {  }                         |
| states                | - pending                    |
| url                   | https://hook-url.example.com |
+-----------------------+------------------------------+

Events to report

EventDescription
environment.access.addA user has been granted access to the environment
environment.access.removeA user has been removed from the environment
environment.activateA branch has been “activated” with an environment
environment.backupA user triggered a snapshot
environment.branchA branch has been created using the management console
environment.deactivateA branch has been “deactivated”. The code is still there but the environment was destroyed
environment.deleteA branch has been deleted
environment.initializeThe master branch of the project initialized with a first commit
environment.mergeAn active branch has been merged using the management console or API
environment.pushA user pushed code to a branch
environment.restoreA user restored a snapshot
environment.route.createA route has been created using the management console
environment.route.deleteA route has been deleted using the management console
environment.route.updateA route has been modified using the management console
environment.subscription.updateThe master environment has been resized because the subscription has changed, but here are no content changes
environment.synchronizeAn environment has had data or code recopied from its parent environment
environment.update.http_accessHTTP access rules for an environment have been modified
environment.update.restrict_robotsThe block-all-robots feature has been enabled or disabled
environment.update.smtpSending of emails has been enabled or disabled for an environment
environment.variable.createA variable has been created
environment.variable.deleteA variable has been deleted
environment.variable.updateA variable has been modified
project.domain.createA domain has been created and added to the project
project.domain.deleteA domain associated with the project has been removed
project.domain.updateA domain associated with the project has been updated
Previous pageError reference
Next pageBitbucket

Commerce