Notification Agents

You will be notified of events in your system via notification agents.

Basic Operations

We support listing, reading, testing, creating, updating, and destroying Notification agents.

List Notification Agents

You can list out all notification agents here

Request Object

+ URL
  /api/v2/notification/agent

+ Method
  GET

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You should get back an array of notification agents.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [{
      "id": 1,
      "hostid": "811fea00",
      "type": "webhook",
      "enabled": true,
      "json": {
        "url": "https://webhook.site/848eea0b-5652-4725-b480-8f04c5edd423"
      },
      "unix_time": "1597882757129",
      "createdAt": "2020-08-20T00:19:17.130Z",
      "updatedAt": "2020-08-20T00:19:17.130Z"
    },
    {
      "id": 2,
      "hostid": "811fea00",
      "type": "smtp",
      "enabled": true,
      "json": {
        "to": [
          "m.moeller@opendrives.com"
        ],
        "ssl": true,
        "from": "code@opendrives.com",
        "host": "smtp.sendgrid.net",
        "port": "465",
        "secure": true,
        "password": "this_is_the_password",
        "username": "this_is_the_username",
        "requireTLS": false
      },
      "unix_time": "1597882957799",
      "createdAt": "2020-08-20T00:22:37.800Z",
      "updatedAt": "2020-08-20T00:22:37.800Z"
    },
    {
      "id": 3,
      "hostid": "811fea00",
      "type": "twilio",
      "enabled": true,
      "json": {
        "authToken": "qwertyasdf1234567890",
        "accountSid": "poiuylkjhvn23234234",
        "toPhoneNumber": "15551234567",
        "fromPhoneNumber": "15550987654"
      },
      "unix_time": "1597882986680",
      "createdAt": "2020-08-20T00:23:06.681Z",
      "updatedAt": "2020-08-20T00:23:06.681Z"
    }
  ]

Get a Notification Agent

As usual, you can get the details of just one agent if you wish.

Request Object

+ URL
  /api/v2/notification/agent/$ID/details

+ Method
  GET

+ Parameters
  id (string, required, URL Param) - the id of the notification agent to view

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You should get back an array of just your notification agent.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [{
    "id": 1,
    "hostid": "811fea00",
    "type": "webhook",
    "enabled": true,
    "json": {
      "url": "https://webhook.site/848eea0b-5652-4725-b480-8f04c5edd423"
    },
    "unix_time": "1597882757129",
    "createdAt": "2020-08-20T00:19:17.130Z",
    "updatedAt": "2020-08-20T00:19:17.130Z"
  }]

Test a Notification Agent

You can request any given notification agent to send out a test message

Request Object

+ URL
  /api/v2/notification/agent/$ID/test

+ Method
  GET

+ Parameters
  id (string, required, URL Param) - the id of the notification agent to test

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You should get back an array of the id of the notification agent you tested.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [{
    "id": 1
  }]

Create a Notification Agent

Creating a notification agent is fairly open ended, with you supplying the configuration to any available notification agent type

Request Object

+ URL
  /api/v2/notification/agent/create

+ Method
  POST

+ Parameters
  type (string, required, BODY) - the type of agent to create, one of 'twilio', 'smtp', or 'webhook'
  enabled (boolean, required, BODY) - a boolean of 'true' or 'false'. Only enabled agents will recieve event notifications
  json (JSON, required, BODY) - the JSON configuration of any given agent type

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    type: 'webhook',
    enabled: true,
    json: {
      "url": "https://webhook.site/848eea0b-5652-4725-b480-8f04c5edd423"
    }
  }
Twilio JSON object
  accountSid: {
    description: `The secret ID generated by Twilio.`,
    example: `sUpErSeCrEtId1234`,
    required: true,
  },
  authToken: {
    description: `The authorization token generated by Twilio.`,
    example: `sUpErSeCrEtToken1234`,
    required: true,
  },
  fromPhoneNumber: {
    description: `The phone number used to send notifications, from Twilio`,
    example: `+15551234567`,
    required: true,
  },
  toPhoneNumber: {
    description: `The phone number you want to send notifications to`,
    example: `+15551234567`,
    required: true,
  },
SMTP JSON object
host: {
  required: true,
  example: `smtp.mysmtpcoolservice.net`,
},
to: {
  required: true,
  example: `bob@bobs_software_company.com`,
},
from: {
  required: true,
  example: `test@bobs_software_company.com`,
},
username: {
  required: true,
  example: `bobs_software_company`,
},
password: {
  required: true,
  example: `my_cool_password`,
},
port: {
  required: true,
  example: 25,
},
secure: {
  description: `Require a secure connection from the mailer`,
  required: false,
  example: false,
},
requireTLS: {
  description: `Require a TLS connection from the mailer`,
  required: false,
  example: false,
},
Webhook JSON Object
url: {
  description: `The URL where the request should be sent.`,
  example: `http://mywebapp.com`,
  required: true,
}

Response Object

You should get back an array of the id of the notification agent you created.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [{
    "id": 4,
    "hostid": "811fea00",
    "type": "webhook",
    "enabled": true,
    "json": {
      "url": "https://webhook.site/848eea0b-5652-4725-b480-8f04c5edd423"
    },
    "unix_time": "1597884568394",
    "createdAt": "2020-08-20T00:49:28.396Z",
    "updatedAt": "2020-08-20T00:49:28.396Z"
  }]

Update a Notification Agent

Updating a notification agent is similarly easy to creating one.

Request Object

+ URL
  /api/v2/notification/agent/$ID/update

+ Method
  POST

+ Parameters
  id (number, required, URL param) - the identifier of the notification agent
  type (string, optional, BODY) - the type of agent to update, one of 'twilio', 'smtp', or 'webhook'
  enabled (boolean, optional, BODY) - a boolean of 'true' or 'false'. Only enabled agents will recieve event notifications
  json (JSON, optional, BODY) - the JSON configuration of any given agent type

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {
    type: 'webhook',
    enabled: false,
    json: {
      "url": "https://webhook.site/11111111-1111-1111-1111-1111111111"
    }
  }

Response Object

You should get back an array of the id of the notification agent you updated.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [{
    "id": 4,
    "hostid": "811fea00",
    "type": "webhook",
    "enabled": false,
    "json": {
      "url": "https://webhook.site/1111111-1111-1111-1111-11111111111"
    },
    "unix_time": "1597884568394",
    "createdAt": "2020-08-20T00:49:28.396Z",
    "updatedAt": "2020-08-20T00:49:28.396Z"
  }]

Destroy a Notification Agent

Simply pass the id of the agent you wish to destroy.

Request Object

+ URL
  /api/v2/notification/agent/$ID/destroy

+ Method
  POST

+ Parameters
  id (number, required, URL param) - the identifier of the notification agent

+ Headers
  Content-Type: application/json
  token: ThisIsNotARealTokenGenerateYourOwnToken

+ Body
  {}

Response Object

You should get back an array of the id of the notification agent you destroyed.

+ Headers
  X-Powered-By: OpenDrives
  Access-Control-Allow-Origin: *
  Content-Type: application/json; charset=utf-8

+ Body
  [
    4
  ]