Webhooks

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 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.
Screen Shot 2022-10-05 at 6 33 29 AM

Events

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

EventDescriptionURL Attributes
agreement_status_changedFires upon agreement status change. For a list of available statuses, see the response for "Retrieve Agreement."<PROJECT_ID>
<AGREEMENT_ID>
<STATUS>
ahj_lookup_completedFires upon completion of an Authority Having Jurisdiction (AHJ) lookup, which happens upon project creation to assign the project to an AHJ. The <STATUS> field can have a value of succeeded or failed, since the job sometimes fails to assign an AHJ.<PROJECT_ID>
<AHJ_ID>
<STATUS>
asset_createdFires upon an asset being created and ready for download. Will not fire for assets still upload-in-progress. The <ASSET_TYPE> field can be Design DXF, Design Layout, CAD Screenshot, CAD Auto Screenshot, Racking Spec Sheet, Racking Install Manual, Racking Certification, Racking CAD File, Racking Engineering Report, or Racking Bill of Materials.<DESIGN_ID>
<ASSET_ID>
<ASSET_TYPE>
auto_designer_job_completedFires upon AutoDesigner job completion. For a list of available statuses, see the response for "Retrieve AutoDesigner job's status."<DESIGN_ID>
<JOB_ID>
<STATUS>
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_createdFires upon a new design being created in Aurora. The SOURCE of a design can be either app, api, or expert_design_service based on whether the design was created (or duplicated) manually in Aurora, via API, or through the expert design service.<PROJECT_ID>
<DESIGN_ID>
<SOURCE>
design_request_completedFires upon design request status changing to designer_completed.<DESIGN_REQUEST_ID_IN_AURORA>
<STATUS>
design_request_rejectedFires upon design request status changing to designer_rejected.<DESIGN_REQUEST_ID_IN_AURORA>
<STATUS>
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>
lead_createdFires upon a new lead being created in Aurora. The SOURCE of a lead can either be lcai or api based on if the lead was made through LCAI or manually via API.<LEAD_ID>
<SOURCE>
lead_solar_estimation_job_completedFires upon a lead’s Solar Estimation job completion. For a list of available statuses, see the response for "Retrieve Solar Estimation job's status."<LEAD_ID>
<JOB_ID>
<STATUS>
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."<DESIGN_ID>
<JOB_ID>
<STATUS>
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."<DESIGN_ID>
<JOB_ID>
<STATUS>
plan_set_request_status_changedFires upon a plan set request status change. For a list of available statuses, see the documentation for "Plan Sets."<PLAN_SET_REQUEST_ID>
<STATUS>
project_createdFires upon a new project being created in Aurora. The SOURCE of a project can be either app or api based on whether the project was created manually in Aurora, or via API.<PROJECT_ID>
<SOURCE>
project_deletedFires upon a new project being deleted in Aurora. The SOURCE of a project can be either app or api based on whether the project was deleted 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.<PROJECT_ID>
<STATUS>
web_proposal_url_createdFires upon a a Web Proposal URL being generated. The SOURCE of a project can be either app or api based on whether the Web Proposal URL was generated manually in Aurora, or via API.<DESIGN_ID>
<SOURCE>

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
agreement_status_changedhttps://www.yourapp.com?project_id=<PROJECT_ID>&agreement_id=<AGREEMENT_ID>&status=<STATUS>
ahj_lookup_completedhttps://www.yourapp.com?project_id=<PROJECT_ID>&ahj_id=<AHJ_ID>&status=<STATUS>
asset_createdhttps://www.yourapp.com?design_id=<DESIGN_ID>&asset_id=<ASSET_ID>&asset_type=<ASSET_TYPE>
auto_designer_job_completedhttps://www.yourapp.com?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
consumption_profile_changedhttps://www.yourapp.com?project_id=<PROJECT_ID>
design_createdhttps://www.yourapp.com?project_id=<PROJECT_ID>&design_id=<DESIGN_ID>&source=<SOURCE>
design_request_completedhttps://www.yourapp.com?design_request_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>
design_request_rejectedhttps://www.yourapp.com?design_request_id=<DESIGN_REQUEST_ID_IN_AURORA>&status=<STATUS>
lead_changedhttps://www.yourapp.com?lead_id=<LEAD_ID>
lead_convertedhttps://www.yourapp.com?lead_id=<LEAD_ID>&project_id=<PROJECT_ID>
lead_createdhttps://www.yourapp.com?lead_id=<LEAD_ID>&source=<SOURCE>
lead_solar_estimation_job_completedhttps://www.yourapp.com?lead_id=<LEAD_ID>&job_id=<JOB_ID>&status=<STATUS>
panel_irradiance_analysis_job_completedhttps://www.yourapp.com?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
performance_simulation_job_completedhttps://www.yourapp.com?design_id=<DESIGN_ID>&job_id=<JOB_ID>&status=<STATUS>
plan_set_request_status_changedhttps://www.yourapp.com?plan_set_request_id=<PLAN_SET_REQUEST_ID>&status=<STATUS>
project_createdhttps://www.yourapp.com?project_id=<PROJECT_ID>&source=<SOURCE>
project_deletedhttps://www.yourapp.com?project_id=<PROJECT_ID>&source=<SOURCE>
project_status_changedhttps://www.yourapp.com?project_id=<PROJECT_ID>&status=<STATUS>
web_proposal_url_createdhttps://www.yourapp.com?design_id=<DESIGN_ID>&source=<SOURCE>

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

EventAvailable Filter(s)Filter Values
agreement_status_changedSTATUSsent
viewed
signed
cancel-pending
canceled
declined
error
ahj_lookup_completedSTATUSsucceeded
failed
asset_createdASSET_TYPEDesign DXF
Design Layout
CAD Screenshot
CAD Auto Screenshot
Racking Spec Sheet
Racking Install Manual
Racking Certification
Racking CAD File
Racking Engineering Report
Racking Bill of Materials
auto_designer_job_completedSTATUSsucceeded
failed
consumption_profile_changed
design_createdSOURCEapp
api
expert_design_service
design_request_completed--
design_request_rejected--
lead_changed
lead_converted
lead_createdSOURCElcai
api
lead_solar_estimation_job_completedSTATUSsucceeded
failed
panel_irradiance_analysis_job_completedSTATUSsucceeded
failed
performance_simulation_job_completedSTATUSsucceeded
failed
plan_set_request_status_changedSTATUSsubmitted
completed
rejected
project_createdSOURCEapp
api
project_deletedSOURCEapp
api
project_status_changedSTATUSany string value
web_proposal_url_createdSOURCEapp
api

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:

RetryInterval until next retry (approximate)
130 seconds
25 minutes
330 minutes
43 hours
520 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.

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.

Related Tutorials: