Developer guide

Events & webhooks

Connect external workflows to Workroomly with incoming events, reliable retries and processing activity.

On this page

Understand the direction
Capture a lead
Envelope and acknowledgement
Idempotency and retries
Inspect failures and replay
Flow+ webhooks
Incoming event catalog

Understand the direction

The public POST /api/events endpoint receives operations from your application into Workroomly. For example, sending crm.lead.created asks Workroomly to create a lead. It is not a notification sent to your webhook when a user creates a lead in the app.

Pattern	When to use it
Query/Search polling	Your service reads current records periodically. Plan for pagination, reconciliation and rate limits.
Incoming event	Your service asks Workroomly to perform a supported business operation asynchronously.
Flow+ workflow	Configure an internal business trigger, an incoming webhook trigger, or an outbound HTTP request in the authenticated workflow builder.

Use Flow+ to send outbound HTTP requests from your business workflows. For operations sent into Workroomly, use the incoming event names and payloads in the catalog below.

Capture a lead

Connect your lead capture service → incoming event → Event Activity → CRM lead.

In Settings → Developers → API Keys, create an Integration key with explicit CRM permission. A Data Access key cannot send this event.
Open Event Explorer, choose that key, choose crm.lead.created, and select the intended CRM space. Copy its data.target.crm_space_key into your server configuration.
Create an immutable event payload for each submission. Persist its idempotency key and payload before sending. A retry must reuse both.
Send the payload from your server. Keep your credential out of the public capture form.
Save the returned event_id. Open Event Activity in the same workroom and inspect the event until it succeeds. Then open the CRM space and verify the record.

Save the following as event.json, replacing the scope placeholder and example submission ID. The example creates a record; use synthetic data in a test workroom first. Leave stage and status out to use the space’s configured defaults.

{
  "event": "crm.lead.created",
  "version": "2026-01",
  "source": "website-lead-capture",
  "idempotency_key": "website-submission-0001",
  "data": {
    "target": { "crm_space_key": "<YOUR_CRM_SPACE_KEY>" },
    "attributes": {
      "full_name": "Alex Example",
      "email": "alex@example.test",
      "source": "website"
    }
  }
}

Send it with a securely configured WORKROOMLY_INTEGRATION_KEY environment variable:

curl --fail-with-body --silent --show-error \
  'https://api.workroomly.com/api/events' \
  -H "Authorization: Bearer $WORKROOMLY_INTEGRATION_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @event.json

Envelope and acknowledgement

Required envelope fields are event, version, idempotency_key and data. Optional fields are source, occurred_at (ISO 8601), correlation_id and metadata. The event-specific data object can contain target, resource and attributes objects.

Create operations generate their own record IDs. Update/delete operations use data.resource.id, a canonical ID obtained from Query/Search. Do not invent an external reference or substitute a display name. Use Event Explorer for workroom-specific owners, transitions and target choices.

A newly accepted request returns HTTP 202. This acknowledgement means the event was accepted for asynchronous processing, not that the record already exists:

{
  "event_id": "22222222-2222-4222-8222-222222222222",
  "status": "pending",
  "duplicate": false,
  "correlation_id": "",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

Idempotency and retries

The pair API key + idempotency_key identifies a submission. Sending the same normalized payload again returns 200, the existing event_id and duplicate: true. Reusing the key with a changed payload returns 409. Check the HTTP status to distinguish conflicts before retrying.

Persist the original payload, including timestamps and metadata. Do not generate a new timestamp or key on each retry. A new API key has a different idempotency namespace, so coordinate key migration with pending submissions to avoid duplicates.

After a timeout, the server may already have accepted the request. Retry with the same key and payload. Use bounded backoff for transport failures, 429 and transient 5xx responses; inspect 4xx failures before retrying. The complete lead capture example includes retry and idempotency handling.

The worker retries transient/unexpected processing failures up to five times, with increasing delays of 30 seconds per retry. Permanent validation failures and exhausted retries enter dead_letter. These are internal processing retries, not outbound webhook delivery attempts. Ordering and exactly-once side effects are not promised; keep downstream processing idempotent too.

Inspect failures and replay

Event Activity shows pending/processing/succeeded/failed/dead_letter status, attempts and processing details. Open an event to inspect its payload, handler result and correlation information. A moderator can inspect; an owner or admin can replay failed/dead-letter events after the cause has been corrected.

An accepted event can fail later if its target or business rules change. A succeeded transition may also report a pending approval rather than an immediate stage move. Read the result instead of assuming a final business outcome from HTTP 202.

There is no API-key event-status polling endpoint in this public contract. Use the authenticated Event Activity view for processing diagnostics; query the resulting business record when appropriate.

Flow+ webhooks

Flow+ has separate Webhook trigger and HTTP request nodes. Configure these inside an authenticated workflow and use the URL and fields supplied by that workflow. A workflow’s trigger filters, payload mapping and run history belong to that workflow; they are not managed by the public Events endpoint.

For incoming Flow+ webhooks that require a secret, the backend supports X-Workroomly-Timestamp and X-Workroomly-Signature. The signature is v1= followed by the hex HMAC-SHA256 of timestamp + "." + raw request body, using the workflow secret. The accepted timestamp window is five minutes in either direction. Sign exactly the bytes you send. The legacy static secret header is deprecated; this is an inbound verification contract, not an automatic signature on outgoing HTTP requests.

For outbound calls, the HTTP request action lets you configure the URL, method, headers, query parameters, body, timeout and retries. The destination must pass public-network security checks. Supply the destination’s authentication through your workflow’s credential handling; do not reuse your Workroomly API key as a receiver secret. Retry behavior is limited to idempotent HTTP methods. Do not assume an outbound POST is automatically retried or that deliveries are ordered.

A receiver for a configured HTTP action must validate the authentication you configured, durably record a deduplication identifier in the mapped payload, and avoid applying the same operation twice. There is no universal Workroomly outbound payload or signing secret to verify. Use the workflow’s run history to troubleshoot the specific HTTP response.

Incoming event catalog

This catalog lists registered incoming operations and the developer catalog’s declared fields. It is not a subscription catalog. Workroom-specific business validation still applies, including lifecycle transitions, required values and record relationships. Use Event Explorer to build a payload with current choices before automating a new operation.

Find an incoming event

54 results

board.epic.createdboard.*

Create a board epic.

Send with version 2026-01 and an Integration key with board.*. This is an incoming operation, not a subscription name.

Event data fields
Path	Catalog requirement
`data.target.board_key`	Required
`data.attributes.name`	Required
`data.attributes.description`	Optional; operation validation applies
`data.attributes.project_id`	Optional; operation validation applies
`data.attributes.sprint_id`	Optional; operation validation applies
`data.attributes.status_key`	Optional; operation validation applies
`data.attributes.assignee_emails`Separate multiple emails with commas.	Optional; operation validation applies
`data.attributes.start_date`	Optional; operation validation applies
`data.attributes.end_date`	Optional; operation validation applies