Webhooks

Supported exact events: playbook_step.awaiting_approval, playbook_step.vetoed, playbook_step.executed, info_request.sent, info_request.answered, playbook.slack_requested, conversation.created, message.sent, message.received, message.follow_up_requested, message.classified, call.missed, call.completed, voicemail.received, activity.created, activity.updated, activity.deleted, alert.triggered, alert.assistance_requested, campaign.created, campaign.updated, case.assigned, case.created, case.updated, case.rma_updated, case.escalated, contract.created, contract.sent, contract.synced, contract.signed, contract.completed, contract.reminder_requested, contract.voided, customer.created, customer.portal_invite_sent, customer_relationship.created, customer_relationship.updated, invoice.created, invoice.sent, invoice.paid, invoice.overdue, lead.assigned, lead.created, lead.updated, lead.converted, opportunity.assigned, opportunity.created, opportunity.updated, opportunity.won, opportunity.lost, payment.failed, payment.dispute_created, project.assigned, project.created, project.updated, project_item.assigned, project_item.status_changed, project_stage.completed, project_team.assigned, project_report.submitted, property_access.created, quote.accepted, quote.agreement_auto_send_failed, quote.project_handoff_failed, quote.created, quote.updated, quote.sent, quote.viewed, quote.declined, quote.aurora_sync_requested, quote.content.updated, quote.content.calculated, service_appointment.created, service_appointment.updated, service_appointment.deleted, service_appointment.dispatched, service_appointment.en_route, service_appointment.started, service_appointment.completed, service_appointment.cancelled, service_appointment.cannot_complete, service_appointment.issue_created, service_appointment.issue_updated, service_appointment.issue_resolved, service_appointment.job_update_posted, task.assigned, time_block.created, time_block.updated, time_block.deleted, webhook.test, work_order.assigned, work_order.created, work_order.updated, work_order.completed, work_order.canceled.

Supported resource wildcards: conversation.*, message.*, activity.*, alert.*, campaign.*, case.*, contract.*, customer.*, customer_relationship.*, invoice.*, lead.*, opportunity.*, payment.*, project.*, project_stage.*, project_report.*, property_access.*, quote.*, quote.content.*, service_appointment.*, time_block.*, webhook.*, work_order.*. The global * wildcard is intentionally not supported.

Each delivery posts JSON with id, type, apiVersion, organizationId, requestId, occurredAt, actor, data, changedFieldPaths, and context. The data object contains the public resource identity and the context object contains sanitized event metadata.

Delivery headers include X-SolarOS-Event, X-SolarOS-Delivery, X-SolarOS-Timestamp, and X-SolarOS-Signature. Delivery logs may refer to the signature value as solarOS-Signature.

Verify X-SolarOS-Signature before processing a delivery. The header is v1=<hex hmac> where the HMAC-SHA256 input is the timestamp, a period, and the raw request body.

Use X-SolarOS-Timestamp to reject stale deliveries, then compare the expected HMAC with the received signature using constant-time comparison. Signing secrets are generated per webhook endpoint and can be rotated with a 7-day overlap.

Return any 2xx response to mark a delivery successful. Responses with 429 or 5xx status codes, timeouts, and network errors enter retry state; most 4xx responses are treated as terminal failures.

Automatic retry uses exponential backoff from one minute up to one hour and stops after 8 delivery attempts. The sender times out requests after 10 seconds and stores the truncated response body for troubleshooting while it is retained.

Webhook payload retention lasts 30 days and response-body retention lasts 7 days. After payload retention expires, retry and replay return a payload-retention error instead of reconstructing historical data.

Manual retry resends the same retained delivery. Manual replay creates a new delivery copied from the retained payload and links it to the original delivery for audit history.

Manage endpoints from Settings -> Connected apps -> Webhooks. The Owner and Admins can create endpoints, choose event subscriptions, test-fire webhook.test, inspect delivery status, retry, replay, rotate signing secrets, and deactivate endpoints. solarOS does not automatically disable a webhook after repeated failures: each new event is still delivered, with its own retries, until you deactivate the endpoint.

Organization API keys do not manage webhook endpoint configuration in v1; they only create domain events that eligible webhook subscriptions can receive.

Send x-solaros-suppress-webhooks: 1 (1, true, or yes, case-insensitive) on a write request to skip firing webhooks for that request, useful when backfilling records from another system.

Send x-solaros-mutation-source: <value> to label where a write came from. The value is echoed as context.mutationSource on any webhook payload that write does still trigger.