Setup endpoint: HTTPS
Invite marbot to a Slack channel to create a new HTTPS endpoint, or use an existing endpoint ID. The endpoint URL will look like this: https://api.marbot.io/v1/endpoint/$endpoint-ID
. Replace $endpoint-ID
with the ID of your endpoint. You can get this value by asking @marbot for it on your Slack channel.
The same URL is used for the AWS SNS HTTPS endpoint
The HTTPS endpoint can receive GET and POST requests.
AWS examples
3rd party examples
- Bitbucket Pipeline
- RSS feed / Amazon Linux Security Advisories
- Uptime Robot
- Jenkins Pipeline
- New Relic Alerts
- Sumo Logic Scheduled Searches & Monitors
Supported HTTP methods
GET
You can use query parameters to send structured data to marbot. Ensure that the values are URL encoded.
Replace $endpoint-ID
with the ID of your endpoint. You can get this value by asking @marbot for it on your Slack channel. Request using curl
:
curl "https://api.marbot.io/v1/endpoint/$endpoint-ID?message=Uuuuups&details=Something%20went%20wrong&time=2017-06-23T05:53:10Z" |
Results in the following generic alert:
POST
marbot understands the following content types:
application/x-www-form-urlencoded
: Parsed as URL encoded valuesapplication/json
: Parsed as JSONtext/plain
: Parsed as JSON or falls back to plain text
For all other content types, marbot tries to parse the input as JSON and falls back to plain text.
application/x-www-form-urlencoded
When data that has been entered into HTML forms is submitted, the form field names and values are encoded, and application/x-www-form-urlencoded
is included in the message’s Content-Type
header.
Replace $endpoint-ID
with the ID of your endpoint. You can get this value by asking @marbot for it on your Slack channel. Request using curl
:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'message=Uuuuups&details=Something went wrong&time=2017-06-23T05:53:10Z' "https://api.marbot.io/v1/endpoint/$endpoint-ID" |
Results in the following generic alert:
application/json
You can also send JSON over HTTPS POST. Include the Content-Type
header application/json
to indicate that you are sending a JSON-formatted message.
Replace $endpoint-ID
with the ID of your endpoint. You can get this value by asking @marbot for it on your Slack channel. Request using curl
:
curl -X POST -H "Content-Type: application/json" -d '{"message": "Uuuuups", "details": "Something went wrong", "time": "2017-06-23T05:53:10Z"}' "https://api.marbot.io/v1/endpoint/$endpoint-ID" |
Results in the following generic alert:
text/plain
If the text is in JSON format, I will parse it.
Replace $endpoint-ID
with the ID of your endpoint. You can get this value by asking @marbot for it on your Slack channel. Request using curl
:
curl -X POST -H "Content-Type: text/plain" -d '{"message": "Uuuuups", "details": "Something went wrong", "time": "2017-06-23T05:53:10Z"}' "https://api.marbot.io/v1/endpoint/$endpoint-ID" |
Results in the following generic alert:
Otherwise, I will understand the input as plain text.
Replace $endpoint-ID
with the ID of your endpoint. You can get this value by asking @marbot for it on your Slack channel. Request using curl
:
curl -X POST -H "Content-Type: text/plain" -d 'Uuuuups. Something went wrong. 2017-06-23T05:53:10Z' "https://api.marbot.io/v1/endpoint/$endpoint-ID" |
Results in the following generic alert:
Aggregation
marbot checks if the X-Alert-Key
header is present. Incoming events with the same X-Alert-Key
value result in a single alert.
Otherwise, marbot looks at the payload:
- If only one field is transmitted, marbot aggregates incoming events with the same field value.
- If more than one field is transmitted, marbot aggregates incoming events with the same field keys.
Reliability
marbot might not be reachable (request timeout, connection error) or might respond with HTTP status codes of 429, 500-599. In all those cases, the alert source needs to implement a retry logic (with exponential backoff) to re-deliver the alert to marbot until marbot response with HTTP status code 204.
To avoid alert duplicates in the case of retries, marbot checks if the X-Request-Id
header is present. Each X-Request-Id
header value can only be used once every ~24 hours. We recommend to generate a UUID on the alert source and send that UUID to marbot in the X-Request-Id
header.