Skip to content
API Reference/
/
Get a webhook

MyCirrus API - Instrument info, Data and Webhooks (1.0.1)

API documentation for the MyCirrus API

Download OpenAPI description
mycirrus-main.json
mycirrus-main.yaml
Overview
URL
https://www.cirrusresearch.com/support/
Support
support@cirrusresearch.com
License
MIT
Terms of Service
Languages
Servers
Mock server
https://docs.mycirrus.cloud/_mock/apis/mycirrus-main
Production server
https://api.mycirrus.cloud/v1

Instrument info and control

Endpoints for finding and controlling instruments

Operations

Noise data

Endpoints for retrieving historic noise data

Operations

Environmental data

Endpoints for retrieving historic environmental data

Operations

Event data

Endpoints for retrieving historic event data

Operations

System health data

Endpoints for retrieving historic system health data

Operations

Webhook management

Webhooks allow you to receive notifications when new data is available. You can configure webhooks via the API itself or via the console.
To create a webhook, go to the API console and click the "Create Webhook" button.

These are the endpoints you can use to manage your webhooks:

Operations

Create a new webhook

Request

Add a new webhook.

The secret can be set or left blank. If left blank, a random secret will be generated and returned in the response.
This is then used to sign the webhook payloads to verify that they are from MyCirrus.

Requires an API key with the webhooks:write scope.

Security
apikey
Bodyapplication/jsonrequired
idstring

ID of the webhook (auto-generated)

typestringrequired

Type of webhook

Enum"NewMeasurement""NewEvent""InstrumentStatus""CalibrationFinished""SicFinished"
instrumentstringrequired

Serial number of the instrument

urlstring(uri)required

URL to send the webhook message to. Must use HTTPS.

secretstring

Secret used to sign the webhook message. If not set, a random secret will be generated.

curl -i -X POST \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/webhooks \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -d '{
    "id": "xxxxxxxxxxxx",
    "type": "NewMeasurement",
    "instrument": "QT123456",
    "url": "https://example.com/mywebhook",
    "secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }'

Responses

Created

Bodyapplication/json
idstring

ID of the webhook (auto-generated)

typestringrequired

Type of webhook

Enum"NewMeasurement""NewEvent""InstrumentStatus""CalibrationFinished""SicFinished"
instrumentstringrequired

Serial number of the instrument

urlstring(uri)required

URL to send the webhook message to. Must use HTTPS.

secretstring

Secret used to sign the webhook message. If not set, a random secret will be generated.

Response
application/json
{
  "id": "xxxxxxxxxxxx",
  "type": "NewMeasurement",
  "instrument": "QT123456",
  "url": "https://example.com/mywebhook",
  "secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Get a list of webhooks

Request

Get a list of all the current webhooks.

Requires an API key with the webhooks:read scope.

Security
apikey
curl -i -X GET \
  https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/webhooks \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
idstring

ID of the webhook (auto-generated)

typestringrequired

Type of webhook

Enum"NewMeasurement""NewEvent""InstrumentStatus""CalibrationFinished""SicFinished"
instrumentstringrequired

Serial number of the instrument

urlstring(uri)required

URL to send the webhook message to. Must use HTTPS.

secretstring

Secret used to sign the webhook message. If not set, a random secret will be generated.

]
Response
application/json
[
  {
    "id": "xxxxxxxxxxxx",
    "type": "NewMeasurement",
    "instrument": "QT123456",
    "url": "https://example.com/mywebhook",
    "secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
]

Remove a webhook

Request

Remove the webhook with the given id.

Requires an API key with the webhooks:write scope.

Security
apikey
Path
webhookIdstringrequired

ID of the webhook

curl -i -X DELETE \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/webhooks/{webhookId}' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

No Content

Response
No content

Get a webhook

Request

Get the webhook with the given id.

Requires an API key with the webhooks:read scope.

Security
apikey
Path
webhookIdstringrequired

ID of the webhook

curl -i -X GET \
  'https://docs.mycirrus.cloud/_mock/apis/mycirrus-main/webhooks/{webhookId}' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring

ID of the webhook (auto-generated)

typestringrequired

Type of webhook

Enum"NewMeasurement""NewEvent""InstrumentStatus""CalibrationFinished""SicFinished"
instrumentstringrequired

Serial number of the instrument

urlstring(uri)required

URL to send the webhook message to. Must use HTTPS.

secretstring

Secret used to sign the webhook message. If not set, a random secret will be generated.

Response
application/json
{
  "id": "xxxxxxxxxxxx",
  "type": "NewMeasurement",
  "instrument": "QT123456",
  "url": "https://example.com/mywebhook",
  "secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Webhook Messages

Webhooks allow you to receive notifications when new data is available. You can configure webhooks via the API itself or via the console.
To create a webhook, go to the API console and click the "Create Webhook" button.

When a webhook is triggered, a POST request will be sent to the URL you specified. The request will contain a JSON body with the data that triggered the webhook.

When processing the webhook request you must return a 200 OK response to indicate that the data was received successfully.

If a 200 response is not given or the request times out (5 seconds), the webhook will be retried up to 5 times.
To ensure a fast response we recommend you respond immediately and queue any further work to be done later.

If a webhook repeatedly fails you will be notified via email. If it continues to fail it will then be removed.
We cannot guarantee you will get a webhook request for every event so you should occasionally check for new items against the normal API endpoints. When processing events such as new measurements its also recommended to request all data since you last processed it rather than just the 1 new measurement from the request.

These are the types of webhook messages you can receive:

Webhooks