API Credentials, Webhooks, and Integrations

What the developer platform does

Powerlily’s developer platform lets an approved external system read or update supported company data and receive notifications when important records change.

• Use the REST API when your integration needs to request data or perform a supported action.
• Use webhooks when Powerlily should notify your system after an event occurs.
• Use both for a two-way integration that reacts to events and retrieves any additional context it needs.

The developer platform is available on plans that include API access. Managing credentials and webhook endpoints also requires the appropriate company permission.

Open Developer Platform settings

Open company settings and select Developer platform. This workspace contains API credentials, webhook endpoints, recent deliveries, the integration guide, an AI-ready integration brief, and the downloadable OpenAPI schema.

The OpenAPI schema is the authoritative source for current paths, operations, parameters, and request fields. Use it rather than guessing a payload from what appears in the web interface.

Plan the integration first

Before creating access, identify:

• The external application and environment that will connect
• Which Powerlily resources it must read
• Which records it must create or update
• Which events it needs to receive
• Where credentials and webhook secrets will be stored
• Who will own testing, monitoring, rotation, and incident response

Create separate access for development, staging, and production. Do not share one permanent credential across unrelated integrations.

Create an API credential

1. Open Developer platform.
2. Expand Create a credential.
3. Enter a descriptive integration name.
4. Choose an expiry period when appropriate.
5. Select only the permissions the integration requires.
6. Select Create credential.
7. Copy the token immediately and store it in a secret manager.

The token begins with pl_live_ and is shown only once. Powerlily stores a digest rather than a recoverable copy. If the token is lost, revoke it and create a replacement.

Choose least-privilege scopes

Credentials can use global Read or Write access, or narrower resource scopes. Production integrations should normally use resource-specific permissions.

Available resource scopes cover branches, catalogue data, clients, events, invoices, leads, projects, schedules, installed systems, tasks, team members, and workflows. Write scopes are available only for supported resources and operations.

For example, an intake integration that only creates and reads leads should use lead-specific permissions rather than global Write access.

Store credentials securely

• Use trusted server-side code.
• Store tokens and webhook secrets in a secret manager or protected environment variable.
• Never place them in browser JavaScript, a mobile application bundle, a URL, source control, screenshots, or logs.
• Do not email or message production secrets to teammates.
• Rotate access when a secret may have been exposed.
• Revoke credentials that are no longer required.

Authenticate API requests

Send the credential as a Bearer token:

Authorization: Bearer $POWERLILY_API_KEY
Accept: application/json

For POST, PATCH, and PUT requests, also send:

Content-Type: application/json

The API base path is /api/v1. Use the integration guide or OpenAPI schema for the complete URL associated with your Powerlily domain.

Available API resources

The API includes company and operational resources such as:

• Company, branches, and team
• Clients
• Workflows and stages
• Projects and proposals
• Leads
• Invoices and payments
• Tasks and calendar events
• Crew scheduling
• Installed systems
• Equipment catalogue data

Create, update, or delete operations are intentionally limited to supported workflows. Sensitive areas such as generic payment mutation, monitoring credentials, role administration, signing evidence, safety signatures, and destructive company actions are not exposed as unrestricted writes.

Understand responses and pagination

Responses use a structured data and meta envelope. Metadata includes a request ID and API version. Collection responses also include pagination details.

• Use page and per_page for pagination.
• The default page size is 25 and the maximum is 100.
• Use ISO 8601 change filters such as updated_after, updated_before, and created_after.
• Use supported sort fields with sort=field or descending sort=-field.
• Store X-Request-Id from responses for troubleshooting.

Make POST requests idempotent

Every POST should include a unique Idempotency-Key. Reuse the same key only when retrying the identical path and request body.

Powerlily retains an eligible response for 24 hours. Replaying the identical request returns the original result instead of creating a duplicate. Reusing the same key for different content returns HTTP 409.

An idempotency key must contain 8 to 255 characters. Build it from a stable identifier in the source system, such as crm-lead-4242-v1.

Handle rate limits and errors

A credential is limited to 100 requests per minute, with broader safeguards also applied. When the API returns HTTP 429, wait for the number of seconds in Retry-After before retrying.

Common responses include:

• 400: invalid parameters or idempotency key
• 401: missing, expired, revoked, or invalid credential
• 403: the credential lacks the required scope
• 404: the resource is not visible within the authenticated company
• 409: an idempotency key was reused for a different request
• 415: a write request did not use JSON
• 422: validation or deletion failure
• 429: rate limit exceeded

Log the status, stable error code, request ID, and safe contextual details. Do not log the Bearer token or full sensitive payloads.

Revoke a credential

The credentials list shows each name, token prefix, scopes, last-used time, expiry, and whether it remains active. Revoke a credential when an integration is retired, compromised, replaced, or granted more access than it needs.

Revocation takes effect immediately. Requests using that credential will stop working.

Add a webhook endpoint

1. Open Developer platform.
2. Expand Add webhook endpoint.
3. Enter a descriptive name.
4. Enter the production HTTPS receiver URL.
5. Select only the event groups or individual events the receiver needs.
6. Add the endpoint.
7. Copy its whsec_ signing secret into your secret manager.
8. Send a test event and verify the receiver.

Each endpoint has its own secret, subscriptions, enabled state, and delivery history. Use separate endpoints when different receiving systems need different events or operational ownership.

Choose webhook events

Webhook subscriptions cover lifecycle events for:

• Leads and stage changes
• Projects, signatures, and stage changes
• Clients
• Invoices and payments
• Tasks and calendar events
• Schedule blocks
• Installed systems and system status changes

A receiver can subscribe to all events, but narrower subscriptions reduce noise and risk.

Verify webhook signatures

Authenticate every webhook before parsing or acting on it:

1. Read and preserve the exact raw request body.
2. Parse the timestamp and v1 value from Powerlily-Signature.
3. Reject a timestamp more than five minutes from the current time.
4. Compute HMAC-SHA256 over timestamp.raw_body using the complete endpoint secret.
5. Compare the received and expected signatures in constant time.
6. Deduplicate the accepted event using Webhook-Id.

Do not reconstruct the JSON body before verification. Even an equivalent reserialization changes the signed bytes.

Process webhook delivery safely

Webhook delivery is at least once and event ordering is not guaranteed. Your receiver must tolerate duplicates and events arriving later than another related event.

• Persist processed Webhook-Id values.
• Accept the event durably before returning success.
• Return a 2xx response promptly.
• Process business logic asynchronously.
• Make downstream actions idempotent.
• Retrieve current API state when ordering matters.

Understand retries and delivery history

Any 2xx response marks the delivery successful. Timeouts, network failures, and non-2xx responses can be retried up to eight times over approximately four days. An HTTP 410 Gone response disables the endpoint.

Powerlily retains delivery records with attempt and response diagnostics. Review recent deliveries when an integration appears delayed. A manual replay preserves the original event ID, so the receiver’s deduplication rules still apply.

Rotate a webhook secret

Secret rotation takes effect immediately and has no overlap window. Update the receiver securely as part of the same maintenance change, then send a test event.

If a secret may have been exposed, rotate it promptly and inspect delivery history and receiver logs for unexpected activity.

Use the integration tools

The Developer Platform page provides:

• An in-app integration guide
• A copy-ready Markdown brief for an AI coding assistant
• A machine-readable OpenAPI YAML file for Postman, SDK generation, and contract validation
• A resource map and webhook-signature instructions

The downloadable AI brief intentionally contains no live API credential or webhook secret. Add secrets only through the target environment’s secure configuration.

Integration checklist

• Separate development and production credentials exist.
• Each credential has the minimum necessary scopes.
• Tokens and signing secrets are stored outside source code.
• Every POST has a stable idempotency key.
• Rate-limit backoff honors Retry-After.
• Request IDs are logged for diagnostics.
• Webhook signatures are verified against the raw body.
• Five-minute timestamp tolerance is enforced.
• Webhook IDs are deduplicated.
• The receiver returns 2xx only after durable acceptance.
• Test deliveries succeed before production events are enabled.
• Inactive credentials and endpoints are revoked or removed.

Troubleshooting

The API returns 401

Confirm that the full Bearer token is being sent, has not expired, and has not been revoked. Do not use the displayed token prefix as the credential.

The API returns 403

Read the required scope in the response metadata. Create a replacement credential with the necessary least-privilege scope if the integration was intentionally authorized for that operation.

A POST creates conflicts or duplicates

Use a stable idempotency key for the logical request and preserve it across network retries. Never generate a new key for each retry of the same operation.

Webhook verification fails

Verify the unmodified raw request body, the complete whsec_ secret, the timestamp, and the exact timestamp.body message format. Check whether the secret was recently rotated.

The receiver gets the same event twice

This is expected under at-least-once delivery. Deduplicate on Webhook-Id and make event handling idempotent.

A webhook endpoint became disabled

Check whether the receiver returned HTTP 410 Gone. Correct the destination, enable or recreate the endpoint as appropriate, and send a test event.

An integration cannot find a record

API access remains scoped to the authenticated company and supported visibility rules. Confirm that the resource belongs to the company associated with the credential.

Related guides

• Team Members, Roles, and Permissions
• Automating Your Workflow: Triggers, Steps, and Conditions
• Creating Lead Forms and Capturing Website Leads
• Tasks, Events, Notes, Files, and Project History
• Installed Systems, Monitoring, and Service