Webhooks

Suggest Edits

You can use webhooks to stay in sync on customer activity in Aurora for all tenants that have enabled your application. Partner webhooks use the same foundation and API functionality built for customer-facing webhooks. Documentation on available webhook events, expectations for recipients, and best practices can be found here.

The following endpoints are supported for application partner webhook management:

Events

Along with our customer-facing webhook events, partners can have access to the following events. Remember, not every app type has access to every event.

app_status_changed

Triggers upon your app being enabled by an Aurora customer. Possible statuses are enabled or disabled

URL Attributes

  • <APP_ID>
  • <STATUS>
  • <TENANT_ID>
  • <SESSION_TOKEN>

Suggested Template

https://www.yourapp.com/app_status_changed?app_id=<APP_ID>&status=<STATUS>&tenant_id=<TENANT_ID>&session_token=<SESSION_TOKEN>

Available for

  • Racking design apps
  • Site survey apps

site_survey_requested

Triggers upon an Aurora customer requesting a site survey.

URL Attributes

  • <SITE_SURVEY_REQUEST_ID>
  • <TENANT_ID>
  • <SESSION_TOKEN>

Suggested Template

https://www.yourapp.com/site_survey_requested?site_survey_request_id=<SITE_SURVEY_REQUEST_ID>&tenant_id=<TENANT_ID>&session_token=<SESSION_TOKEN>

Available for

  • Site survey apps

Testing webhooks

It’s possible to manually trigger a webhook to test your webhook integration by sending a POST request to /application_partners/{application_id}/webhooks/{webhook_id}/trigger with the following body: 

{
  "application_partner_webhook": {
    "url_parameters": []
  }
}

By default this will fire the webhook with placeholders in the url_template replaced with nonsense values. For example, <PROJECT_ID> in the template would be replaced with a randomly generated, and therefore invalid, UUID. If you wish you can provide overrides for the placeholders:

{
  "application_partner_webhook": {
    "url_parameters": [
      { "name": "<PROJECT_ID>", "value": "your project id" },
      ...
    ]
  }
}

If you provide a <TENANT_ID> value, a matching <SESSION_TOKEN> will be generated in your sandbox environment. Production environments will always generate a random, invalid <TENANT_ID> and <SESSION_TOKEN> value for security reasons. Note that you cannot provide a custom <SESSION_TOKEN> value in any environment.

On success, a 204 No Content response will be returned.

Considerations

Webhooks for partners differ from customer webhooks in several ways:

  • The path for each API endpoint will begin with /application_partners/{application_id} rather than /tenant/{tenant_id}
  • The bearer token used will by your application key
  • The request body for POST and PUT requests are wrapped in a top level application_partner_webhook rather than webhook
  • When a you create a webhook, you will receive a notification for an event from any customer who has enabled your app.
  • The list of permitted events will vary by integration type, just as API access is only granted for endpoints necessary for the application to complete its work.
  • Most partner webhooks are required to include 2 additional url parameters in the url_template for each webhook:
    • <TENANT_ID> will be populated with the unique id of the Aurora tenant where the event took place
    • <SESSION_TOKEN> will contain a single-use session token
      Together, this information can be used to request a temporary bearer token to access Aurora APIs on behalf of the tenant as explained in Authorization Flows.

Updated 4 months ago