api authentication setup guide
To integrate the B2B signal inbox API from userhero.io, you must first establish secure authentication credentials within your developer dashboard. Navigate to the settings panel and generate a new API key, ensuring you assign it the necessary read and write permissions for accessing customer signals. Store this key securely in an environment variable rather than hardcoding it into your application source files. This initial step prevents accidental exposure of sensitive access tokens during routine code reviews or public repository pushes. Once generated, configure your application’s HTTP headers to include the Authorization token with every request sent to the endpoint. This ensures that only authorized systems can retrieve real-time customer engagement data and update signal statuses without triggering security alerts or rate limits imposed by the platform.
Also worth reading: How to integrate customer signals into a unified B2B SaaS inbox for product and support teams? · How to use userhero customer signal inbox for b2b? · What are the benefits of using a B2B customer signal tool?
After securing authentication, focus on implementing the core integration logic for handling incoming signals. You will need to set up a webhook listener that accepts POST requests from userhero.io whenever a new B2B customer signal is detected. Parse the JSON payload carefully to extract relevant fields such as customer ID, signal type, and timestamp. Store this information in your local database to enable downstream processing by your product and support teams. Implement error handling routines to retry failed requests and log any malformed responses for debugging purposes. This robust approach ensures seamless data flow between the signal inbox and your internal systems, allowing teams to respond promptly to critical customer interactions while maintaining data integrity and operational efficiency across all connected services.
webhook event payload structure
The payload arrives as a POST with a JSON body containing an event envelope: a unique event id, the event type (such as signal.created or signal.resolved), a timestamp, and a nested data object holding the signal itself. The data object includes the account identifier, the contact who triggered the signal, the signal category, a severity score, and the raw source reference so you can trace back to the original interaction. Sign the verification by comparing the X-Signature header against an HMAC of the raw body using your endpoint's shared secret, and reject anything that fails before parsing.
To integrate, register your endpoint URL in the dashboard under integrations, choose the event types you want delivered, and store the generated secret in your environment. Respond to each delivery with a 200 within ten seconds; if you need to do heavy processing, acknowledge first and queue the work. Retries follow an exponential backoff schedule for up to 24 hours, and deliveries are ordered per account but not globally, so use the timestamp field rather than arrival order when sequencing events.
signal filtering configuration rules
Integration starts by mapping your existing webhook endpoints to the signal inbox API's event schema, which accepts POST payloads at the /v1/signals endpoint. Authenticate with a scoped API key generated from your workspace settings, then batch incoming events in groups of up to fifty to stay within rate limits. Most teams at userhero.io route product usage events and support ticket metadata through a single collector service before forwarding, which keeps deduplication logic in one place and prevents duplicate signals from skewing priority scoring.
Once the pipeline is live, configure filtering rules so only high-intent signals reach the inbox: set thresholds for signal strength, exclude events older than a defined window, and tag signals by source so routing rules can assign them to the right team. Test with sandbox mode first, which mirrors production behavior without notifying recipients, then flip to live after verifying that your dedupe keys and timestamp formats match the expected ISO 8601 standard.
dashboard user permission levels
For the signal inbox API, settle the permission model by separating ingestion from human action. Use one workspace-scoped service token for inbound signals and webhook subscriptions; that token can create signals and update delivery status but cannot read customer records or change dashboard users. Dashboard people authenticate through their existing roles: viewers get read-only signal access, analysts can triage and update signals, and admins manage tokens, integrations, and workspace settings. This removes the ambiguous shared-admin-key pattern and makes audit trails meaningful.
At the API boundary, enforce the same role checks as the dashboard rather than trusting the caller to send a role. Map token scopes to actions, log every write with the acting user or service identity, and let support teams grant temporary analyst access without exposing admin credentials. For userhero.io customers, this keeps signal ingestion reliable while ensuring dashboard permissions remain the source of truth for who can see, reply to, or resolve customer signals. Start with workspace service tokens and delegated user sessions, then add finer per-inbox scopes only when a real enterprise need appears.
error handling response codes
For integration, treat HTTP status as the contract and map failures before writing signal data. A 401 means rotate the API token; 403 means the workspace lacks the required scope or inbox permission; 422 means the payload failed validation, so surface field-level errors to the operator and do not retry unchanged. A 429 should honor Retry-After and back off with jitter. For 5xx responses, retry with exponential backoff only when the request is idempotent; attach a client-generated idempotency key to signal creation so a timeout cannot duplicate records. Log correlation IDs from UserHero responses alongside your own request ID.
Persist failed ingests in a dead-letter queue rather than dropping them, and reconcile ambiguous timeouts by fetching the signal using the idempotency key or external ID before retrying. Treat 4xx errors except 408 and 429 as terminal and alert on repeated terminal failures. This gives product and support teams reliable inbox delivery while keeping error handling deterministic.
api vs manual workflow
| Feature | API Integration | Manual Workflow |
|---|---|---|
| Speed | Real-time synchronization | Batch processing delays |
| Accuracy | Automated data validation | Human error prone |
| Scalability | Handles high volume easily | Limited by staff capacity |
| Maintenance | Low ongoing effort | High continuous overhead |