Userorbit Webhooks Reference

Userorbit Webhooks provide a mechanism to receive real-time notifications about events happening within your Userorbit account. Instead of continuously polling the Userorbit API for changes, webhooks push data to your specified endpoint (an HTTP URL) whenever a relevant event occurs. This allows for immediate integration with your internal systems, triggering custom workflows, or updating external databases.

Properties

Endpoint URL — string — The URL where Userorbit will send POST requests when events are triggered. This endpoint must be publicly accessible and capable of handling HTTP POST requests.
Secret Key — string — An optional secret key used to generate a digital signature for each webhook payload. This allows your application to verify that the webhook request originated from Userorbit and has not been tampered with.
Event Types — array of strings — A list of specific events for which you want to receive notifications. Common Userorbit events include:
- feedback.new: A new piece of user feedback has been submitted.
- feedback.status_changed: The status of a feedback item has been updated.
- announcement.new: A new announcement has been published.
- survey.response_new: A new response to a survey has been received.
- checklist.completed: A user has completed a checklist.
- product_tour.completed: A user has completed a product tour.
Payload Format — JSON object — All webhook payloads are sent as JSON objects in the request body. The general structure includes an event type and a data object containing details about the event.
- event: A string indicating the type of event that occurred (e.g., feedback.new).
- timestamp: A Unix timestamp indicating when the event occurred.
- data: A JSON object containing the specific details related to the event. The structure of this object varies depending on the event type.

Examples

Below is an example of a typical webhook payload for a feedback.new event:


{
  "event": "feedback.new",
  "timestamp": 1678886400,
  "data": {
    "feedback_id": "fb_abcdef123456",
    "user_id": "usr_7890abcd",
    "user_email": "user@example.com",
    "title": "New feature request: Dark Mode",
    "description": "It would be great to have a dark mode option for the dashboard.",
    "status": "new",
    "product_area": "UI/UX",
    "created_at": "2023-03-15T10:00:00Z",
    "url": "https://admin.userorbit.com/feedback/fb_abcdef123456"
  }
}

This example demonstrates how a new feedback submission would be delivered to your endpoint, providing all necessary details to process it.

Notes

Verifying Webhook Signatures: To ensure the authenticity and integrity of incoming webhook requests, Userorbit generates a signature using your provided secret key. This signature is typically included in an HTTP header (e.g., X-Userorbit-Signature). Your endpoint should:
1. Retrieve the signature from the request header.
2. Recompute the signature using your secret key and the raw request body.
3. Compare your computed signature with the one from the header. If they match, the webhook is valid.
This prevents unauthorized parties from sending fake webhook events to your application.
Retry Behavior: If your endpoint fails to acknowledge a webhook (e.g., by returning an HTTP status code outside the 200-299 range, or timing out), Userorbit will typically retry sending the webhook after a short delay. This retry mechanism usually follows an exponential backoff strategy for a limited number of attempts to ensure delivery, but eventually, failed webhooks may be dropped. Ensure your endpoint responds quickly and reliably.
Testing Webhooks: When developing and testing your webhook endpoint, consider using tools like Ngrok or Webhook.site to expose your local development environment to the internet and inspect incoming webhook payloads. This allows you to debug your handler without deploying it to a production server.
Security Considerations: Always treat incoming webhook data as untrusted until its signature has been verified. Ensure your endpoint uses HTTPS to encrypt communication.

Help Center