Simple Backup Webhooks

Updated by John Gerger on Nov 07, 2019
Article Code: kb/1180

Description

The Simple Backup Service now supports Webhooks which send push notifications to an HTTP endpoint specified by the customer. This FAQ addresses commonly asked questions about the service. For a walkthrough of how to use Webhooks, see Configuring Webhooks and Consuming Notifications.

Q: What exactly is a Webhook?

A: Webhooks make it possible to create push notification solutions. Backup events (e.g. "Backup failures") are sent in real-time to a web endpoint configured for the Webhook. Whenever an event occurs, a JSON message is sent as an HTTP POST request.

Q: In what scenario would I use a Webhook?

A: Webhooks provide the opportunity to immediately see what's going on within your backup environment. This allows you to quickly and easily monitor and respond to backup events.

Q: What triggers a Webhook?

A: There are currently Webhooks for four major categories: Backup Failure, Backup Partial Success, Missing Backups, and Backup Success.

  • Backup Failure Triggered on a backup that has completed with a status of Failure.
  • Backup Partial Success. Triggered on a backup that has completed with a status of Partial Success.
  • Missing Backups Triggered when a server has not initiated a backup within 1 hour of the scheduled start time on the backup policy.
  • Backup Success. Triggered on a backup that has completed with a status of Success.

Q: Where do I go to set up a Webhook?

A: Webhooks are available within the Simple backup UI in a sub-menu called "Webhooks". Customers can set a target URL for each Webhook event listed.

Q: Are there any requirements for the service that receives the Webhook notification?

A: Listener services must be on the public internet in a location reachable by the Lumen Cloud platform. If a customer plans on consuming this data within an internal system, consider using a reverse proxy or another mechanism to forward traffic from a public-facing web service to an internal system.

Q: What happens if the destination is unreachable?

A: There is no guaranteed delivery with Lumen Cloud Webhooks. We make a single attempt to send a message to the designated endpoint and if it fails, it is not retried. This means two things: (1) design your endpoints to be highly available and withstand failures of any single component in the solution, and (2) rely on a combination of Webhooks and daily email reports to monitor your backup environment completely.

Q: What data is sent in the Webhook event notification?

Example payload for a Backup FAILURE event type:

{
  "text": "Status: FAILED - Account: TEST - Server: testServerId20190201013933 - Account Policy Name: TestAccountPolicyName20190201013933 - Restore Point Id: c56b1fd4-b566-4044-a696-0f1311ffdeee - Finished Date/Time: 2019-02-01 01:39:40 UTC",
  "status": "FAILED",
  "account": "TEST",
  "server": "testServerId20190201013933",
  "serverPolicyId": "a73fb66e-7e77-41fa-b303-11600820d13a",
  "accountPolicyName": "TestAccountPolicyName20190201013935",
  "accountPolicyId": "96ac27e5-3e70-4ec8-8275-286c4a436ab4",
  "restorePointId": "c56b1fd4-b566-4044-a696-0f1311ffdeee",
  "finishedDate": "2019-02-01 01:39:40 UTC"
}

Example payload for a Backup PARTIAL Success event type:

{
  "text": "Status: PARTIAL_SUCCESS - Account: TEST - Server: IL1TESTWIND0803 - Account Policy Name: andy-test-windows-20181019 - Restore Point Id: 5e641ec2-24c1-40aa-a93a-d75e66f37d1220190131170408 - Finished Date/Time: 2019-02-01 01:05:00 UTC",
  "status": "PARTIAL_SUCCESS",
  "account": "TEST",
  "server": "IL1TESTWIND0803",
  "serverPolicyId": "5e641ec2-24c1-40aa-a93a-d75e66f37d12",
  "accountPolicyName": "andy-test-windows-20181019",
  "accountPolicyId": "ab8e34e6-15e1-4940-86b0-77ab68854746",
  "restorePointId": "5e641ec2-24c1-40aa-a93a-d75e66f37d1220190131170408",
  "finishedDate": "2019-02-01 01:05:00 UTC"
}

Example payload for a MISSING Backup event type:

{
  "text": "testServerId20181228013921 missed a backup expected at 2019-02-01T20:00:04.289Z for policy [TestAccountPolicyName20181228013921] with server policy id [5f3876b7-6fc9-4610-b619-85f6c01e231d] and storage region [US EAST]",
  "account": "TEST",
  "server": "testServerId20181228013921",
  "serverPolicyId": "5f3876b7-6fc9-4610-b619-85f6c01e231d",
  "accountPolicyName": "TestAccountPolicyName20181228013921",
  "accountPolicyId": "2f62f2a3-d1be-496e-ab0a-e2fa25c4b152",
  "expectedDate": "2019-02-01T20:00:04.289Z"
}

Example payload for a Backup SUCCESS event type:

{
  "text": "Status: SUCCESS - Account: TEST - Server: UC1BAADUBUN1605 - Account Policy Name: TestAccountPolicyName20181228013921 - Restore Point Id: d46dc104-2119-4288-a59c-f04f59ffb1e920190201212354 - Finished Date/Time: 2019-02-01 21:23:57 UTC",
  "status": "SUCCESS",
  "account": "TEST",
  "server": "UC1BAADUBUN1605",
  "serverPolicyId": "d46dc104-2119-4288-a59c-f04f59ffb1e9",
  "accountPolicyName": "TestAccountPolicyName20181228013921",
  "accountPolicyId": "04ea6d8d-90a5-45a3-a67d-84c2dfe20141",
  "restorePointId": "d46dc104-2119-4288-a59c-f04f59ffb1e920190201212354",
  "finishedDate": "2019-02-01 21:23:57 UTC"
}