Skip to main content

Overview

Webhooks can be used to keep in sync with Opensolar. To create a webhook, provide Opensolar with an endpoint and the appropriate headers.

Endpoint​

EndpointDescriptionParameters
GET /api/orgs/:org_id/webhooks/Get Org webhooks
POST /api/orgs/:org_id/webhooks/Create Org webhookstrigger_fields, payload_fields, enabled (true/false), debug (true/false), endpoint
PATCH /api/orgs/:org_id/webhooks/:idUpdate Org webhookstrigger_fields, payload_fields, enabled (true/false), debug (true/false), endpoint

Parameters

  • debug (boolean): required when creating a webhook. Currently 'debug' flag is not used.
  • enabled (boolean): required when creating a webhook.
  • endpoint (string): required when creating a webhook.
  • trigger_fields (json): Webhooks will be triggered only if the fields in this list are updated. To use default values, set the field to null.
  • payload_fields (json): The fields in this list will be included in the webhook's request. To use default values, set the field to null.
info

  • When the trigger_fields is set to empty or null, then the webhook will be triggered when any change is made to the Project, Contact, and Event models. This might cause unnecessary webhook calls and we suggest being explicit with the trigger_fields.

  • Only the models and fields specified in the trigger_fields will trigger the webhook. For example, a webhook with ["contact.first_name", "contact.last_name"] as its trigger will not process updates made to the Event and Project models.

  • Models followed by a .* such as project.*, event.*, and contact.* allows a webhook to include all fields attached to that model. This applies to both trigger_fields & payload_fields.

warning
  • Setting the trigger_fields to ["project.*", "event.*", "contact.*"] isn't recommended since this might cause unnecessary webhook calls.

Default values

  • trigger_fields: ["contact.*", "event.*", "project.address", "project.zip", "project.state", "project.lat", "project.lon", "project.country", "project.locality", "project.county", "project.contacts", "project.identifier", "project.notes", "project.systems.price_including_tax", "project.systems.output_annual_kwh", "project.systems.modules", "project.systems.inverters", "project.systems.others", "project.systems.batteries", "project.systems.kw_stc", "project.stage", "project.system_sold", "project.payment_option_sold", "project.sold_date", "project.installation_date", "project.system_installed", "project.assigned_installer_role", "project.assigned_role", "project.assigned_site_inspector_role", "project.events_data", "project.usage", "project.utility_tariff_or_guess", "project.utility_tariff_proposed"]

  • payload_fields: ["contact.*", "event.*", "project.address", "project.zip", "project.state", "project.lat", "project.lon", "project.country_iso2", "project.locality", "project.county", "project.contacts_data.email", "project.contacts_data.family_name", "project.contacts_data.first_name", "project.contacts_data.id", "project.contacts_data.phone", "project.systems.price_including_tax", "project.systems.output_annual_kwh", "project.systems.url", "project.systems.modules", "project.systems.inverters", "project.systems.others", "project.systems.batteries", "project.systems.kw_stc", "project.id", "project.identifier", "project.notes", "project.site_notes", "project.actions", "project.stage", "project.system_sold", "project.payment_option_sold", "project.sold_date", "project.installation_date", "project.system_installed", "project.assigned_installer_role_data.user_email", "project.assigned_installer_role_data.id", "project.assigned_installer_role_data.first_name", "project.assigned_installer_role_data.family_name", "project.assigned_installer_role_data.phone", "project.assigned_role_data.user_email", "project.assigned_role_data.id", "project.assigned_role_data.first_name", "project.assigned_role_data.family_name", "project.assigned_role_data.phone", "project.assigned_site_inspector_role_data.user_email", "project.assigned_site_inspector_role_data.id", "project.assigned_site_inspector_role_data.first_name", "project.assigned_site_inspector_role_data.family_name", "project.assigned_site_inspector_role_data.phone", "project.events_data", "project.usage", "project.utility_tariff_or_guess.data", "project.utility_tariff_proposed_or_guess.data"]

Example​

Creating a Webhook​

Sample POST request and response (Creating a webhook):

Request 
curl "https://api.opensolar.com/api/orgs/:org_id/webhooks/"
--request POST
-H "Content-Type: application/json"
-H "Authorization: Bearer <token>"
-d
'{"endpoint": "https://somesolar.com/api/",
"headers": "{\"Authorization\": \"Token <your-token>\"}",
"enabled": true, "debug": false,
"trigger_fields":["project.contract_date"],
"payload_fields":["project.*"]}'

Sample PATCH request and response (Update an existing webhook):

Request 
curl "https://api.opensolar.com/api/orgs/:org_id/webhooks/123/"
--request PATCH
-H "Content-Type: application/json"
-H "Authorization: Bearer <token>"
-d
'{"enabled": false,
"trigger_fields":["project.installation_date"],
"payload_fields":["project.*"]}'