Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: ed90daf1c1
Fetching contributors…

Cannot retrieve contributors at this time

445 lines (397 sloc) 11.325 kb

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-type Description
application/json A valid JSON payload

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
deploy:db:failed_to_store_payload 503 Our database isn't responding or timed out
deploy:provider:not_supported 400 You tried to deploy an invalid payload
deploy:github:no_pkg_json 502 We couldn't get package.json from github. This may happen because you are trying to deploy a private repo
deploy:auth:bad_creds 401 You didn't provide valid Basic Auth in your HTTP request
deploy:github:download_tarball 502 Failed to get the tarball from github
deploy:nodejitsu:upload_tarball 502 Failed to upload the tarball to nodejitsu
deploy:tar:* 500 There was a system failure when extracting the tar
deploy:nodejitsu:start_app 500 Failed to start nodejitsu application
deploy:no_payload 400 You 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

Key Type Description
limit Integer Number of log entries to display per page
skip Integer Number of log entries to skip. e.g. if you saw 10 already, you might do a skip=10

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
mw:auth:not_you 401 You are trying to get status that don't belong to you
mw:auth:auth_server_down 500 We couldn't verify your credentials
mw:auth:unauthorized 401 Your username/password combination doesn't match our records
mw:auth:no_username 401 Your user document is in a bad state, contact support
status:db:not_found 404 Didn't find that log entry
status:db:get_by_id 500 The database couldn't complete your query
status:db:query_fail 500 The 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

Key Type Description
include_docs Boolean Will 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

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
mw:auth:not_you 401 You are trying to get status that don't belong to you
mw:auth:auth_server_down 500 We couldn't verify your credentials
mw:auth:unauthorized 401 Your username/password combination doesn't match our records
mw:auth:no_username 401 Your user document is in a bad state, contact support
status:db:query_fail 500 The database couldn't complete your query
status:changes:timeout 408 The socket connection timeout. Please re-connect
status:changes:fatal 500 There 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.

Key Type Description
app String Will restrict the usage of this token to a application. If not provided a wildcard will be used.

Response Headers

Header Type Description
x-api-uuid String - UUID A unique id for your request. We keep tracks of these to help you thru support
x-api-version String - Semantic Version The current version of our API. Follows semver rules. Major version is in the url as first parameter.

Errors

Error Status Code Reason
mw:auth:not_you 401 You are trying to get status that don't belong to you
mw:auth:auth_server_down 500 We couldn't verify your credentials
mw:auth:unauthorized 401 Your username/password combination doesn't match our records
mw:auth:no_username 401 Your user document is in a bad state, contact support
auth:github:get_user_failed 500 When 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_failed 500 We tried to update the user but it failed. Just like above, reasons are varied so contact support if you see this
auth:github:no_credentials 400 Credentials were not provided. Check query string parameters for details
auth:github:bad_credentials 400 Credentials were provided but not in the username:password format. Check query string parameters for details
auth:github:github_pairing_failed 401 We tried to authenticate with github but it failed
Jump to Line
Something went wrong with that request. Please try again.