Webhooks

Aurora uses webhooks to notify your applications when an event occurs in your tenants.

Use cases

Common webhook use cases include:

Notifying your team that Aurora Expert Design service finished building a roof model, and the design is ready for panel placement
Keeping Aurora design details in sync with those in your CRM
Triggering post-sales workflow in your IT ecosystem on homeowner's e-signing a solar installation agreement
Replacing batched polling of Aurora objects for statuses with real-time webhook-based notifications

How webhooks work

A webhook is a single message sent by Aurora to your application's webhook subscription URL. A webhook contains payload in path parameters and, optionally, authentication information in the headers.

A webhook subscription is a persisted data object that you can create, update, and delete using Aurora's APIs or UI (pictured). The webhook subscription describes the event that your application needs to be notified about and a destination where Aurora should send webhooks of the specified event. When the event occurs, the webhook subscription sends a relevant payload to your destination.

Events

For a list of all available events, see Events.

URL template

Aurora webhooks are fired as GET requests to a URL generated using a template provided by you. When creating a webhook subscription, you may specify which of the event's attributes should be included in the webhook's URL. For example, URL template

https://www.yourapp.com/auto_designer_job_completed?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>

would result in GET requests that look like this

https://www.yourapp.com/auto_designer_job_completed?design_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&job_id=5cf99a21-5717-4562-b3fc-2c963f66abc6&status=succeeded

Note that you can also include static attributes like ?aurora_event=design_request_rejected in URL templates.

Securing your webhooks

To keep communications between Aurora and your application secure, we only include proprietary identifiers and statuses in webhook payloads. You can ensure that the payload is encrypted by using an HTTPS URL.

Your webhooks can optionally include authentication information to verify that they came from Aurora rather than someone claiming to be Aurora. We offer two types of webhook authentication:

Header-based Token Authentication

Provide your auth token using a key-value pair in the webhook's headers.

//POST /tenants/{tenant_id}/webhooks

"webhook": {
          "description": "Aurora - AutoDesigner Webhook",
          "event": "auto_designer_job_completed",
          "url_template": "https://www.webhookclient.com...",
          "enabled": true,
          "header_auth_key": "X-Aurora-Webhook-Token",
          "header_auth_value": "2dbcbba1-9f64-4c07-86dc-02effcbeafa6"
     }

Basic Auth

Provide basic auth username and password to be sent with each webhook.

//POST /tenants/{tenant_id}/webhooks

"webhook": {
          "description": "Aurora - AutoDesigner Webhook",
          "event": "auto_designer_job_completed",
          "url_template": "https://www.webhookclient.com...",
          "enabled": true,
          "basic_auth_username": "[email protected]",
          "basic_auth_password": "Powering the future 0f solar together!"
     }

Filters

Provide filters for your URL attributes so that webhooks are only sent on specific events.

A webhook filter defines a list of allowed values for a URL attributes. When an event occurs in Aurora, the values for the URL attributes will be checked against the webhook's filters. Webhooks will only trigger if the value for all URL attributes matches the associated filters. If a webhook subscription has no filters associated with it, no filtering will be done and the webhook will be sent.

For example, a project_status_changed webhook with the filters:

{
  "<STATUS>": ["In Progress", "Completed"]
}

would only send a webhook notification when a Project is transitioned to "In Progress" or "Completed". All other project_status_changed events would be filtered out, and no webhook notification would be sent.

For a list of available filters for each event, see Events.

Considerations

Timeouts. Your application is expected to respond within 10 seconds. Otherwise, the webhook will time out.

Retries. Aurora has a retry mechanism for failed webhook notifications. If your application doesn't respond within 10 seconds, or responds with a 3xx/4xx/5xx status code, Aurora will try to deliver the webhook 5 more times. Each retry will use the most recent webhook definition so that errors in URLs or credentials can be corrected. Disabling or deleting a failing webhook will prevent subsequent retries.

Retries occur at exponentially increasing intervals over 24 hours:

Retry	Interval until next retry (approximate)
1	30 seconds
2	5 minutes
3	30 minutes
4	3 hours
5	20 hours

If your application has an outage that causes you to miss all retries, we can resend notifications within 30 days of the original event. Please contact your Aurora account representative for assistance.

Auto-disabled subcriptions. If all retries for a webhook subscription fail within a 48 hour period, the webhook will be automatically disabled to avoid excessive load on Aurora's systems. A webhook subscription must have at least 100 attempts within the 48 hours to be considered for auto-disabling. After the failure is resolved, you can re-enable the webhook subscription in the webhooks dashboard or using Webhooks API.

Multiple subscriptions. You can have multiple webhook subscriptions associated with an event with a maximum of 5 subscriptions per event per tenant.

Ordering. Ordering between events is not guaranteed. For example, it's possible that you'll receive a webhook with status signed before you receive a webhook with status viewed for an agreement. Your endpoint should handle this accordingly.

Best practices

Respond quickly. It's important to respond to the webhook request as quickly as possible. A common pattern is to store the payload in a message queue for later processing by a background worker.

Handle duplicate webhooks. Although we try not to send the same webhook twice, in some rare cases, that might happen. Receiving the same webhook a second time in a row should have no additional effect. You can detect duplicate webhooks by examining universally unique identifiers included in the payload (e.g. design_request_id, job_id) or just comparing the payload directly to the previous state.