How do I trigger hooks before and after a deployment?

When it comes to deployments, some environments require extra tasks to be executed before or after files are uploaded. Beanstalk supports two types of deployment hooks: pre- and post-deploy web hooks and a post-deploy shell command hook.

Pre- and Post-deploy web hooks

Deployment web hooks are supported for all three deployment server types: FTP, SFTP and SSH. They require that you have a web server running on your remote server that can be accessed by Beanstalk whenever a web hook is triggered. When the hook is triggered, Beanstalk will connect to your web server at the URL you specify and submit information about the triggered deployment in JSON format. You can setup the URL that your web hook is listening to on the server setup page.

Make sure your web server is always returning a 2XX HTTP response to Beanstalk in order for it to be considered a success. If a pre-deployment hook returns anything other than a 2XX response, the deployment will not proceed and no files will be uploaded. If the post-deployment hook failed, Beanstalk will mark the entire deployment as failed to alert you of the issue.

If you would like to protect your web hook with a password, you can use basic HTTP authentification by providing the username and password in the web hook URL, like this:

https://myuser:mylogin@www.mydomain.com/myhook

Please note, if you have a firewall on your server you’ll need to whitelist Beanstalk’s IPs in order to receive the hook.

Post-deploy shell commands

The shell command hooks are available only for SFTP servers. Beanstalk will execute any shell commands on your remote server after the deployment is finished. Make sure that all of the specified shell commands return an exit status 0 in order for them to be considered a success. Otherwise the deployment will be marked as failed so you can see that there was a problem.

Sample of JSON data posted by Beanstalk

{
  // Username of the author
  "author":"author username",

  // Repository from which data was or will be deployed
  "repository":"beanstalk",

  // Full name of the author
  "author_name":"John Smith",

  // Commit message
  "comment":"example",

  // Email of the author
  "author_email":"johnsmith@example.com",

  // Server to which data was deployed or will be deployed
  "server":"server example",

  // Environment from which data was or will be deployed
  "environment":"development",

  // Revision to which the deployment will be updated
  "revision":"5",

  // Time when deployment happened - timezone is included, will be null for pre hook
  "deployed_at":"deployed at date",

  // Default source control URL of the repository (legacy attribute, may return Git or HTTPS URL)
  "repository_url":"git@xyz.git.beanstalkapp.com:/abc.git",

  // HTTPS URL of the repository (supports both Git and SVN)
  "repository_url_https":"https://xyz.git.beanstalkapp.com:/abc.git",

  // Git SSH URL of the repository (Git only)
  "repository_url_ssh":"git@xyz.git.beanstalkapp.com:/abc.git",

  // Identifier of the payload, in case you consume JSON from many vendors
  "source":"beanstalkapp"
}

PHP users please note that in order to get contents of a POST request in PHP you need to use the following code snippet:

`file_get_contents(php://input;);

Content-Type header

For historical reasons Beanstalk will send a Content-Type header with value "application/x-www-form-urlencoded" with each hook.