Send Docs Feedback

Set up notifications using webhooks

Introduction

A webhook defines an HTTP callback handler that is triggered by an event. You can create webhooks and configure them to handle event notifications, as an alternative to using the monetization notification templates, as described in Set up notifications using notification templates.

Webhooks are valid for triggering event notifications for adjustable notification rate plans only, as described in Specifying adjustable notification plan details.

To set up notifications using webhooks, complete the following steps using the Edge Management UI, or Management and Monetization API:

  1. Create webhooks that define the callback handlers for the notification events using the UI or API.
  2. Set up the callback handler.
  3. Configure the notification condition that triggers the webhook as the action using the UI or API.

Creating webhooks using the UI

Create and manage webhooks using the UI as described in the following sections.

Viewing all webhooks using the UI

Select Admin > Webhooks.

The Webhooks page is opened and the list of current webhooks is displayed.

Creating a webhook using the UI

To create a webhook using the UI:

  1. Select Admin > Webhooks to open the Webhooks page.
  2. Click +Webhook.
  3. Enter the following information (all fields are required).
    Field Description
    Name Name of the webhook.
    Url URL of the callback handler that will be called when the event notification is triggered. See Setting up the callback handler.
  4. Click Save.

The webhook is added to the list and enabled by default.

Updating a webhook using the UI

To update a webhook using the UI:

  1. Select Admin > Webhooks.
  2. Click the name of the webhook that you want to edit to open the webhook update dialog box.
  3. Edit the webhook fields, as required.
  4. Click Save.

Enabling or disabling a webhook using the UI

To enable or disable a webhook using the UI:

  1. Select Admin > Webhooks.
  2. Perform one of the following tasks:
    • Select the Enabled checkbox associated with the webhook that you want to enable.
    • Deselect the Enabled checkbox associated with the webhook that you want to disable.

Deleting a webhook using the UI

To delete a webhook using the UI:

  1. Select Admin > Webhooks.
  2. Click Delete associated with the webhook that you want to delete.

The webhook is deleted and removed from the list.

Creating webhooks using the API

Create and manage webhooks using the API as described in the following sections.

Viewing all webhooks using the API

To view all webhooks, issue a GET request to /organizations/{org_name}/webhooks. For example:

$ curl -H "Content-Type: application/json " -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" -u email:password

The following provides an example of the results returned:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Viewing a webhook using the API

To view a single webhook, issue a GET request to /organizations/{org_name}/webhooks/{webhook_id}.

For example:

$ curl -H "Content-Type: application/json " -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" -u email:password

The following provides an example of the results:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Creating a webhook using the API

To create a webhook, issue a POST request to /organizations/{org_name}/webhooks. You must pass the name of the webhook and the URL of the callback handler that will be called when the event notification is triggered.

For example, the following creates a webhook named webhook3 and assigns callbackhandler3 to the webhook:

$ curl -H "Content-Type: application/json " -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" -d \    '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

The following provides an example of the result:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Updating a webhook using the API

To update a webhook, issue a POST request to /organizations/{org_name}/webhooks/{webhook_id}. Pass the updates in the body of the request.

For example, the following updates the callback handler associated with webhook1:

$ curl -H "Content-Type: application/json " -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" -d \    '{
    "postURL": "http://mycompany.com/callbackhandler4"
    }' \
    -u email:password

The following provides an example of the result:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Enabling or disabling a webhook using the API

You can enable or disable a webhook. If you disable the webhook, it will not be triggered when an event occurs.

To enable or disable a webhook, issue a POST request to /organizations/{org_name}/webhooks/{webhook_id}, as you did when updating a webhook, and set the enabled attribute in the request body to true or false, respectively.

For example, the following enables webhook3:

$ curl -H "Content-Type: application/json " -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" -d \    '{
    "enabled": "true"
    }' \
    -u email:password

The following provides an example of the result:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Deleting a webhook using the API

To delete a webhook, issue a DELETE request to /organizations/{org_name}/webhooks/{webhook_id}.

To specify whether or not to force the deletion of the webhook if there are processes in progress, set the forceDelete query parameter to true or false. The forceDelete query parameter is enabled (true) by default.

For example, the following deletes webhook3:

$ curl -H "Content-Type: application/json " -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" -u email:password

Setting up the callback handler

The following shows the format of the JSON request that is sent to the callback handler defined by a webhook when an event notification is triggered. You must ensure that the callback handler processes the request appropriately.

{
	"orgName": "{org_id}",
	"developerEmail": "{dev_email}",
	"developerFirstName": "{first_name}",
	"developerLastName": "{last_name}",
        "companyName": "{company_name}",
	"applicationName": "{app_name}",
	"packageName": "{api_package_name}",
	"packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
	"ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
	"developerRatePlanQuotaTarget": {quota_target},
	"quotaPercentUsed": {percentage_quota_used},
	"ratePlanStartDate": {rateplan_startdate}, 
	"ratePlanEndDate": {rateplan_enddate},
	"nextBillingCycleStartDate": {next_billing_cycle_startdate},
	"products": ["{api_product_name}","{api_product_name}"],
	"developerCustomAttributes": [],
	"triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Configuring notification conditions and actions for webhooks using the UI

Configure the notification conditions and actions for webhooks using the UI as described in the following sections.

Configuring a notification condition and action for a webhook using the UI

To configure a notification condition and action for webhooks using the UI:

  1. Create an adjustable notification rate plan, as described in Specifying adjustable notification plan details.
  2. Select Publish > Packages to view the rate plans.
  3. Click +Notify in the Actions column for the rate plan.

    The Notfications dialog is displayed.

  4. Configure the notification condition under Percentage of Target by specifying a percentage of the target number of transactions at which time you want a notification to be triggered:
    • To set an exact percentage, enter the percentage in the at/from field and leave the to field blank.
    • To set a percentage range, enter the start and end percentage in the at/from and to fields, respectively, and an increment value in the step field. By default, notifications are sent in 10% increments within the specified range.

    The Notify At field is updated to reflect each percentage of the target number of transactions that will trigger an event.

  5. To configure additional notification conditions, click + and repeat step 4.
  6. Configure the notification action under Webhooks by selecting one or more webhooks to manage callback handling when notifications are triggered.
  7. Click Create Notification.

Updating a notification condition and action for a webhook using the UI

To update a notification condition and action using the UI:

  1. Select Publish > Packages to view the rate plans.
  2. Click +Notify in the Actions column for the rate plan.
  3. Click Edit.
  4. Modify the values, as required.
  5. Click Save Notification.

Deleting a notification condition and action for a webhook using the UI

To delete a notification condition and action using the UI:

  1. Select Publish > Packages to view the rate plans.
  2. Click +Notify in the Actions column for the rate plan.
  3. Click Delete Notification.

Configuring notification conditions and actions for webhooks using the API

To configure a notification condition that triggers a webhook using the API, use the procedure described in Configuring notifications and actions using the API and use the attributes described in this section.

To configure the notification condition (notificationCondition), use the following attribute values. For more information, see Configuration settings for notification conditions.

Attribute Value
RATEPLAN ID of the adjustable notification rate plan.
PUBLISHED TRUE to indicate that the adjustable notification rate plan must be published.
UsageTarget Percentage of the target number of transactions at which time you want a notification to be triggered.

This attribute enables you to notify developers when they're nearing or have reached their target number of transactions for an adjustable notification rate card plan that they've purchased. For example, if a developer has purchased an adjustable notification rate plan and the target number of transactions for the developer has been set to 1000, you can notify them when they reached 800 transactions (80% of the target number of transactions), 1000 transactions (100%), or 1500 transactions (150%).

  • To set an exact percentage, enter %= n. For example, %= 80 will send notifications when the percentage of the target number of transactions reaches 80%.
  • To set a percentage range, enter the start and end percentages, and value by which to increment as follows: %= start to end by n. For example, a value of %= 80 to 100 by 10 will send notifications when the percentage of the target number of transactions reaches 80%, 90%, and 100%.

To configure the notification action, under actions set the following values. For more information, see Configuration settings for notification actions.

Attribute Value
actionAttribute WEBHOOK to trigger a webhook.
value ID of the webhook that you defined in the previous section, Creating webhooks.

The following provides an example of how to create a notification condition that triggers a webhook when the percentage of the target number of transactions reaches 80%, 90%, 100%, 110%, and 120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

For information about viewing, updating, and deleting a notification condition and action, see:

Webhook response codes

The following summarizes the webhook response codes and how they are interpreted by the system.

Response Code Description
2xx Succcess
5xx

Failed request. The system will retry the request up to three times in 5-minute intervals.

Note: The read and connection timeouts for webhook requests are 3 seconds each, which can result in failed requests.

Other response Failed request. The system will not retry the request.

 

Help or comments?