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

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 REST APIs. 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

With access to either Sync or Design API, you can create webhook subscriptions to all the following events.

EventDescriptionURL Attributes
lead_createdFires upon a new lead being created in Aurora.<LEAD_ID>
lead_changedFires upon a new lead being changed in Aurora.<LEAD_ID>
lead_convertedFires upon a lead being converted into a project in Aurora.<LEAD_ID>
<PROJECT_ID>
project_createdFires upon a new project being created in Aurora. The SOURCE of a project can be either api or app based on whether the project was created manually in Aurora, or via API.<PROJECT_ID>
<SOURCE>
project_status_changedFires upon a project status change. Unlike other webhook statuses, a project status can be any string.<STATUS>
<PROJECT_ID>
consumption_profile_changedFires upon any change to a consumption profile. Note that the change may not affect any fields exposed through the API.<PROJECT_ID>
design_request_completedFires upon design request status changing to designer_completed.<STATUS>
<DESIGN_REQUEST_ID_IN_AURORA>
design_request_rejectedFires upon design request status changing to designer_rejected.<STATUS>
<DESIGN_REQUEST_ID_IN_AURORA>
auto_designer_job_completedFires upon AutoDesigner job completion. For a list of available statuses, see the response for "Retrieve AutoDesigner job's status."<STATUS>
<DESIGN_ID>
<JOB_ID>
panel_irradiance_analysis_job_completedFires upon irradiance analysis job completion. Note that this will only send once panel irradiance is completed, and will not send for roof irradiance jobs. For a list of available statuses, see the response for "Retrieve irradiance analysis job's status."<STATUS>
<DESIGN_ID>
<JOB_ID>
performance_simulation_job_completedFires upon performance simulation job completion. For a list of available statuses, see the response for "Retrieve performance simulation job's Status."<STATUS>
<DESIGN_ID>
<JOB_ID>
asset_createdFires upon an asset being created and ready for download. Will not fire for assets still upload-in-progress.<DESIGN_ID>
<ASSET_ID>
agreement_status_changedFires upon agreement status change. For a list of available statuses, see the response for "Retrieve Agreement."<STATUS>
<PROJECT_ID>
<AGREEMENT_ID>

URL template

Aurora webhoooks 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

EventSuggested URL Template
lead_created?lead_id=<LEAD_ID>
lead_changed?lead_id=<LEAD_ID>
lead_converted?lead_id=<LEAD_ID>&project_id=<PROJECT_ID>
project_created?project_id=<PROJECT_ID>&source=<SOURCE>
project_status_changed?project_id=<PROJECT_ID>&status=<STATUS>
consumption_profile_changed?project_id=<PROJECT_ID>
design_request_completed?design_request_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>
design_request_rejected?design_request_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>
auto_designer_job_completed?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
panel_irradiance_analysis_job_completed?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
performance_simulation_job_completed?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
asset_created?design_id=<DESIGN_ID>&asset_id=<ASSET_ID>
agreement_status_changed?project_id=<PROJECT_ID>&agreement_id=<AGREEMENT_ID>&status=<STATUS>

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 assure 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.

Webhook Filters act as an allow-list for values of 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_created 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.

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 9 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 4-5 hours:

RetryInterval until next retry (approximate)
130 seconds
260 seconds
32 minutes
45 minutes
511 minutes
620 minutes
741 minutes
81 hour, 10 minutes
91 hour, 50 minutes

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.