Free for Open Source
Fork on Github

Webhooks API Documentation

Deploy

POST /
POST /1/deploy

Deploy a new application with a given payload.

Check Sample Payloads for examples. This method is normally called by a github or travis web-hook.

You must configure the github webhook to use the travis webhook. Works under the assumption that if your repository has a .travis.yml file and that contains at least one webhook notification we shouldn't deploy from the github request, but instead wait until travis triggers the notify event and calls our API. This effectively means that if travis tests don't pass your application does not get deployed.

curl -X POST -u username -d @file https://webhooks.nodejitsu.com/1/deploy

Authentication can use a pair of user:pass or user:apiToken.

Accept

Content-typeDescription
application/jsonA valid JSON payload

Response Headers

HeaderTypeDescription
x-api-uuidString - UUIDA unique id for your request. We keep tracks of these to help you thru support
x-api-versionString - Semantic VersionThe current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

ErrorStatus CodeReason
deploy:db:failed_to_store_payload503Our database isn't responding or timed out
deploy:provider:not_supported400You tried to deploy an invalid payload
deploy:github:no_pkg_json502We couldn't get package.json from github. This may happen because you are trying to deploy a private repo
deploy:auth:bad_creds401You didn't provide valid Basic Auth in your HTTP request
deploy:github:download_tarball502Failed to get the tarball from github
deploy:nodejitsu:upload_tarball502Failed to upload the tarball to nodejitsu
deploy:tar:*500There was a system failure when extracting the tar
deploy:nodejitsu:start_app500Failed to start nodejitsu application
deploy:no_payload400You didn't provide a payload

Status

GET /1/status/:user/webhooks
GET /1/status/:user/webhooks/:application

Gets the install status for a specific user. Useful to determine if the deploy worked, or why it failed. :user is your Nodejitsu username and :application is your application name.

curl -u dscape  https:/webhooks.nodejitsu.com/1/status/dscape/webhooks/hello-world-api-flatiron?limit=10\&skip=20

Query String Parameters

KeyTypeDescription
limitIntegerNumber of log entries to display per page
skipIntegerNumber of log entries to skip. e.g. if you saw 10 already, you might do a skip=10

Response Headers

HeaderTypeDescription
x-api-uuidString - UUIDA unique id for your request. We keep tracks of these to help you thru support
x-api-versionString - Semantic VersionThe current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

ErrorStatus CodeReason
mw:auth:not_you401You are trying to get status that don't belong to you
mw:auth:auth_server_down500We couldn't verify your credentials
mw:auth:unauthorized401Your username/password combination doesn't match our records
mw:auth:no_username401Your user document is in a bad state, contact support
status:db:not_found404Didn't find that log entry
status:db:get_by_id500The database couldn't complete your query
status:db:query_fail500The database couldn't complete your query

Changes

GET /1/status/:user/changes/
GET /1/status/:user/changes/:id

Streams log files as you deploy application with a changes stream. When you provide an id it will just return that entry and close the http connection.

curl -u dscape https://webhooks.nodejitsu.com/1/status/dscape/changes?include_docs=true

Query String Parameters

KeyTypeDescription
include_docsBooleanWill add an extra property doc (containing the full log document) to each log entry that is displayed. Use "auto" for automatically expanding errors and summarizing ok statuses

Response Headers

HeaderTypeDescription
x-api-uuidString - UUIDA unique id for your request. We keep tracks of these to help you thru support
x-api-versionString - Semantic VersionThe current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

ErrorStatus CodeReason
mw:auth:not_you401You are trying to get status that don't belong to you
mw:auth:auth_server_down500We couldn't verify your credentials
mw:auth:unauthorized401Your username/password combination doesn't match our records
mw:auth:no_username401Your user document is in a bad state, contact support
status:db:query_fail500The database couldn't complete your query
status:changes:timeout408The socket connection timeout. Please re-connect
status:changes:fatal500There was an error in the underlying connection

Auth

POST /1/auth/github

Tries to get authorization from github, so elevated privileges can be used on that service. This will give us access to get working code from your repositories and change the status of a specific pull request

curl -X POST -u nodejitsuUser https://webhooks.nodejitsu.com/1/auth/github \
  --data '{"credentials":"githubUser:githubPass"}' \
  --header "Content-type: application/json"

Query String Parameters

The app parameter exists so you can restrict usage of a token to a individual application. This is useful can then commit status can only be applied to that specific application, and other third party tokens will not be returned.

However be careful, when specifying an application we will not be able to use these credentials to access the repository (because when we do that for the first time we still don't know the app name, we learn that from the package.json file).

Bottom line if you want to do deployments for private repositories do not specify app or you will fail.

KeyTypeDescription
appStringWill restrict the usage of this token to a application. If not provided a wildcard will be used.

Response Headers

HeaderTypeDescription
x-api-uuidString - UUIDA unique id for your request. We keep tracks of these to help you thru support
x-api-versionString - Semantic VersionThe current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

ErrorStatus CodeReason
mw:auth:not_you401You are trying to get status that don't belong to you
mw:auth:auth_server_down500We couldn't verify your credentials
mw:auth:unauthorized401Your username/password combination doesn't match our records
mw:auth:no_username401Your user document is in a bad state, contact support
auth:github:get_user_failed500When retrieving the user from the nodejitsu api we got a non 200 response. The api might be down, or perhaps authorization credentials where changed
auth:github:update_user_failed500We tried to update the user but it failed. Just like above, reasons are varied so contact support if you see this
auth:github:no_credentials400Credentials were not provided. Check query string parameters for details
auth:github:bad_credentials400Credentials were provided but not in the username:password format. Check query string parameters for details
auth:github:github_pairing_failed401We tried to authenticate with github but it failed

Getting Started

Learn how to set up Nodejitsu's tool for app deployment and be ready for action.

See the guide