Webhooks

Webhooks in OnSched v3 provide a way for your application to receive real-time notifications about key events in your scheduling system, such as appointment creations, cancellations, and reminders. This allows you to integrate OnSched with external services (e.g., CRMs, notification systems, or custom workflows) without polling the API.

Webhooks are scoped to a specific Location and Company in your OnSched account. They are triggered asynchronously and sent as HTTP POST requests to a URL you specify. Each webhook can subscribe to one or more events (triggers) and include custom headers.

Important Notes:

• Webhooks are "fire-and-forget": OnSched sends the request but does not retry on failure (e.g., 5xx errors). Failed deliveries are logged on the OnSched side but not guaranteed.
• No built-in signature or HMAC verification is provided for security. Secure your endpoint using IP whitelisting, API keys in custom headers, or other methods.
• All webhook requests include a Content-Type: application/json header.
• Authentication for managing webhooks (creating/listing) requires a valid API token with appropriate permissions (via the /v3/auth endpoints).
• Webhooks are only sent for active locations and companies.

Supported Events (Triggers)

Webhooks can be configured to trigger on the following appointment-related events. The trigger field in the payload will match one of these exact strings:

• NEW_APPOINTMENT: Fired when a new appointment is successfully created (e.g., via booking or admin creation).
• APPOINTMENT_CONFIRMED: Fired when an appointment moves from pending to confirmed status (e.g., after customer approval).
• APPOINTMENT_CANCELLED: Fired when an appointment is cancelled by any party (admin, customer, or auto-cancellation).
• APPOINTMENT_RESCHEDULED: Fired when an existing appointment is updated with a new time slot.
• APPOINTMENT_REMINDER: Fired when a reminder is sent to the customer (e.g., via email/SMS before the appointment). Note: This may appear as APPOINTMENT_REMINDER_SENT in some API documentation.

These events are appointment-centric. Future versions may expand to other entities (e.g., resource updates). Check the API changelog for updates.

Setting Up Webhooks

Webhooks are managed via the OnSched v3 REST API. All endpoints are under /v3/webhook and require:

• A valid Bearer token (obtained via /v3/auth/login or API key).
• Company verification (the token must belong to the company owning the location).

Base URL: https://api.onsched.com/v3 (or your custom domain if configured).

List Existing Webhooks (GET /v3/webhook)

Retrieve all active webhooks for a specific location.
Query Parameters:

• locationId (required, UUID): The ID of the location to query.

Example Request:

GET /v3/webhook?locationId=123e4567-e89b-12d3-a456-426614174000 Authorization: Bearer your-api-token

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "url": "https://your-app.com/webhooks/onsched",
      "headers": {
        "X-Custom-Header": "secret-value",
        "Authorization": "Basic your-basic-auth"
      },
      "triggers": ["NEW_APPOINTMENT", "APPOINTMENT_CANCELLED"],
      "active": true,
      "LocationId": "123e4567-e89b-12d3-a456-426614174000",
      "CompanyId": "987fcdeb-1234-5678-9abc-def012345678",
      "createdAt": "2025-10-20T10:00:00Z",
      "updatedAt": "2025-10-20T10:00:00Z"
    }
  ]
}

Error Responses:

• 401 Unauthorized: Invalid token.
• 403 Forbidden: No access to the location/company.
• 404 Not Found: Location not found.
• 400 Bad Request: Missing locationId.

Managing Webhooks via the OnSched App
In the OnSched web app (v3):

1. Navigate to Settings > Locations > [Your Location] > Integrations.
2. Scroll to the Webhooks section.
3. Add/edit webhooks using the form (URL, events, custom headers).
4. Test by creating a sample appointment and checking your endpoint logs.