You can use webhooks to keep your app 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. Detailed documentation on webhooks at Aurora including URL templates, expectations for recipients, and best practices can be found in the customer facing API docs.

Managing Webhooks

Partner app webhooks can be managed via API. To access each endpoint, please use your application key.

Create a webhook

POST https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/webhooks

{
  "partner_application_webhook": {
    "event": "app_status_changed",
    "url_template": "https://www.yourapp.com/app_status_changed?app_id=<APP_ID>&status=<STATUS>&tenant_id=<TENANT_ID>&session_token=<SESSION_TOKEN>",
    "description": "My webhook",
    "enabled": true,
    "header_auth_key": "sample_key",
    "header_auth_value": "sample_value"
  }
}

Please note, your webhook will be required to have <SESSION_TOKEN> and <TENANT_ID> as URL parameters. This ensures your app is able to request a temporary token to access the triggering tenant's data.

Your webhook is also required to use either header-based token auth or basic auth and must use HTTPS.

For documentation on each field, and more configuration options, see the Create Webhook endpoint documentation in the Sync API.

List Webhooks

GET  https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/webhooks

For more details, see the List Webhooks endpoint documentation in the Sync API.

Retrieve Webhook

GET  https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/webhooks/{webhook_id}

For more details, see the Retrieve Webhook endpoint documentation in the Sync API

Update Webhook

PUT  https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/webhooks/{webhook_id}

{
  "partner_application_webhook": {
    "enabled": false
  }
}

For more field options and considerations, see the Update Webhook endpoint documentation in the Sync API

Delete Webhook

DELETE  https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/webhooks/{webhook_id}

For more details, see the Delete Webhook endpoint documentation in the Sync API

Events

The events available to your app depend on your app type. See the table below for a complete list of webhook events your app can subscribe to. If you would like to subscribe to an event outside your app's list, please contact Aurora.

For a list of all generally available events, and their documentation, see the Sync API Events page.

For a list of all partner specific events, and their documentation, see the Partner events page.

Available events by app type

Filtering

In addition to the filtering functionality available to our customers, as a partner you can filter webhooks by tenant ID. This may be useful for architectures that require different webhook endpoints for each tenant.

When creating or updating the webhook, you simply need to provide a <TENANT_ID> as a filter parameter. The URL provided will only be invoked for events matching the tenant ID provided.

POST https://api.aurorasolar.com/partner_applications/{application_id}/webhooks

{
  "application_partner_webhook": {
    "url_template": "https://yourdomain.com?tenant_id=<TENANT_ID>&session_token=<SESSION_TOKEN>",
    ...
    "filters": {
      "<TENANT_ID>": ["tenant id to filter on"]
    }
  }
}

Testing webhooks

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

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

By default this will fire the webhook with template variables 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

• 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 app type, similar to how 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.
• Partner webhooks must use HTTPS and header-based token auth or basic auth.