API curl requests¶

Use curl to send HTTP or HTTPS API requests. Note that you must specify skipTLSVerification: true on your request to test the webhook endpoint over HTTP.

Example curl request:

curl -u test-user:$TOKEN -X POST "https://msr-example.com/api/v0/webhooks" -H "accept: application/json" -H "content-type: application/json" -d "{ \"endpoint\": \"https://webhook.site/441b1584-949d-4608-a7f3-f240bdd31019\", \"key\": \"maria-testorg/lab-words\", \"skipTLSVerification\": true, \"type\": \"TAG_PULL\"}"

Example JSON response:

{
  "id": "b7bf702c31601efb4796da59900ddc1b7c72eb8ca80fdfb1b9fecdbad5418155",
  "type": "TAG_PULL",
  "key": "maria-testorg/lab-words",
  "endpoint": "https://webhook.site/441b1584-949d-4608-a7f3-f240bdd31019",
  "authorID": "194efd8e-9ee6-4d43-a34b-eefd9ce39087",
  "createdAt": "2019-05-22T01:55:20.471286995Z",
  "lastSuccessfulAt": "0001-01-01T00:00:00Z",
  "inactive": false,
  "tlsCert": "",
  "skipTLSVerification": true
}

Subscribe to events¶

To subscribe to events, send a POST request to /api/v0/webhooks with the following JSON payload:

Example usage:

{
  "type": "TAG_PUSH",
  "key": "foo/bar",
  "endpoint": "https://example.com"
}

Payload keys¶
Key	Description
`type`	The event type to subscribe to.
`key`	The namespace/organization or repo to subscribe to. For example, `foo/bar` to subscribe to pushes to the `bar` repository within the namespace/organization `foo`.
`endpoint`	The URL to send the JSON payload to.

You must supply a “key” to scope a particular webhook event to a repository or a namespace/organization. If you are an MSR admin, you can omit the “key”, in which case a POST event notification of the specified type will be triggered for all MSR repositories and namespaces.

Receive a payload¶

When your specified event type occurs, MSR will send a POST request to the given endpoint with a JSON-encoded payload that has the following wrapper:

{
  "type": "...",
  "createdAt": "2012-04-23T18:25:43.511Z",
  "contents": {...}
}

Payload keys¶
Key	Description
`type`	Applies to the event type received at the specified subscription endpoint.
`contents`	Refers to the payload of the event itself. Each event is different, therefore the structure of the JSON object in `contents` will change depending on the event type. Refer to Content structure for more details.

Test payload subscriptions¶

Before subscribing to an event, you can view and test your endpoints using fake data. To send a test payload, send a POST request to /api/v0/webhooks/test with the following payload:

{
  "type": "...",
  "endpoint": "https://www.example.com/"
}

Change type to the event type that you want to receive. MSR will then send an example payload to your specified endpoint. The example payload sent is always the same.