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 Platform API, you can create webhook subscriptions to all the following events.

Event Name

Description

URL Attributes

design_request_completion

Fires upon design request status changing to designer_completed.

<STATUS>
<DESIGN_REQUEST_ID_IN_AURORA>

design_request_rejection

Fires upon design request status changing to designer_rejected.

<STATUS>
<DESIGN_REQUEST_ID_IN_AURORA>

auto_designer_job_completion

Fires upon AutoDesigner job completion for jobs started via the REST API. For a list of available statuses, see the response for "Retrieve AutoDesigner job's status."

<STATUS>
<DESIGN_ID>
<JOB_ID>

irradiance_analysis_job_completion

Fires upon irradiance analysis job completion for jobs started via the REST API. For a list of available statuses, see the response for "Retrieve irradiance analysis job's status."

<STATUS>
<DESIGN_ID>
<JOB_ID>

performance_simulation_job_completion

Fires upon performance simulation job completion for jobs started via the REST API. For a list of available statuses, see the response for "Retrieve performance simulation job's Status."

<STATUS>
<DESIGN_ID>
<JOB_ID>

agreement_status_changed

Fires upon agreement status change. For a list of available statuses, see the response for "Retrieve Agreement."

<STATUS>
<PROJECT_ID>
<AGREEMENT_ID>

project_status_changed

Fires upon a project status change. Unlike other webhook statuses, a project status can be any string.

<STATUS>
<PROJECT_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_completion?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_completion?design_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&job_id=5cf99a21-5717-4562-b3fc-2c963f66abc6&status=succeeded

EventSuggested URL Template
design_request_completion?design_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>
design_request_rejection?design_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>
auto_designer_job_completion?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
irradiance_analysis_job_completion?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
performance_simulation_job_completion?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
agreement_status_changed?project_id=<PROJECT_ID>&agreement_id=<AGREEMENT_ID>&status=<STATUS>
project_status_changed?project_id=<PROJECT_ID>&status=<STATUS>

Note that you can also include static attributes like ?aurora_event=desing_request_rejection 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_completion",
          "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_completion",
          "url_template": "https://www.webhookclient.com...",
          "enabled": true,
          "basic_auth_username": "[email protected]",
          "basic_auth_password": "Powering the future 0f solar together!"
     }

Considerations

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

Retries. We do not retry webhook delivery at the moment but will offer retries soon.

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.