Chapter 13. Webhooks

By the end of this section, you will be able to configure and take action on the webhooks in the Developer Portal.

The use of webhooks allows you to tightly integrate 3scale with your back-office workflow. When specified events happen within the 3scale system, your applications will be notified with a webhook message, and you can use the data such as from a new account signup to populate your Developer Portal.

13.1. Introducing webhooks

A webhook is a custom HTTP callback triggered by an event selected from the available ones in the Webhooks configuration window. When one of these events occurs, the 3scale system makes an HTTP or HTTPS request to the URL address specified in the webhooks section. On your end, you can configure the listener to invoke some desired behavior such as event tracking.

To configure webhooks:

  1. Navigate to Account Settings > Integrate > Webhooks. Account Settings is the gear icon located in the upper right of the window.

  2. Indicate the behavior for webhooks. There are two options:

    • Webhooks enabled: Select this checkbox to enable or disable webhooks.

    • Actions in the admin portal also trigger webhooks: Select this checkbox to trigger a webhook when an event happens. Consider the following:

      • When making calls to the internal 3scale APIs configured with the triggering events, use an access token; not a provider key.
      • If you leave this checkbox cleared, only actions in the Developer Portal trigger webhooks.
  3. Specify the URL address for notification of the selected events when they trigger.
  4. Select the events that will trigger the callback to the indicated URL address.

Once you have configured the settings, click Update webhooks settings to save your changes.

13.2. Webhooks format

The format of the webhook is always the same. It makes a post to the endpoint with an XML document of the following structure: 

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>

Each element provides information:

  • <type>: Gives you the subject of the event such as application, account, and so on.
  • <action>: Specifies what has been done, by using values such as updated, created, deleted.
  • <object>: Constitutes the XML object itself in the same format that is returned by the Account Management API. To check this, you can use our interactive ActiveDocs.

If you need to provide assurance that the webhook was issued by 3scale, expose an HTTPS webhook URL and add a custom parameter to your webhook declaration in 3scale. For example: https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue. Decide on the parameter name and value. Then, inside your webhook endpoint, check for the presence of this parameter value.

13.3. Troubleshooting

If you experience an outage for your listening endpoint, you can recover failed deliveries. 3scale will consider a webhook delivered if your endpoint responds with a 200 code. Otherwise, it will retry 5 times with a 60 seconds gap. After any recovery from an outage, or periodically, you should run a check and if applicable clean up the queue. You can find more information about the following methods in ActiveDocs:

  • Webhooks list failed deliveries
  • Webhooks delete failed deliveries