Manage Webhooks

The Butlr platform provides self-service capabilities for managing webhooks through GraphQL API. Users can create, update, and delete webhooks programmatically.

Overview

Butlr's self-service webhooks empower users to manage real-time event notifications programmatically. Through our GraphQL API, users can create, update and delete webhooks, as well as retrieve a comprehensive list of all configured webhooks. This self-service capability streamlines integration, customization and troubleshooting, enabling users to efficiently leverage Butlr's event data for informed decision-making and seamless application interactions.

Available Operations

Create Webhooks

GraphQL (Example)

mutation CreateWebhooks ($input: [WebhookCreateInput!]!) {
  createWebhooks(input: $input) {
    id
    name
    event_types
    endpoint_config {
      url
      http_timeout
      api_key {
        key
        value
      }
      basic_auth {
        username
        password
      }
    }
  }
}

Update Webhooks

GraphQL (Example)

mutation UpdateWebhooks ($input: [WebhookUpdateInput!]!) {
  updateWebhooks(input: $input) {
    id
    name
    event_types
    endpoint_config {
      url
      http_timeout
      api_key {
        key
        value
      }
      basic_auth {
        username
        password
      }
    }
  }
}

Delete Webhooks

GraphQL (Example)

mutation DeleteWebhooks ($input: [ID!]!) {
  deleteWebhooks(ids: $input) 
}

List Webhooks

GraphQL (Example)

query {
    webhooks {
        id
        name
        event_types
        endpoint_config {
            url
            http_timeout
            api_key {
                key
                value
            }
            basic_auth {
                username
                password
            }
        }
    }
}

Schemas

Mutations

Schema

type Mutation {
  """
  Mutation to create one or more new webhooks. Each webhook will be set up with a unique configuration, including event subscriptions and endpoint details.
  """
  createWebhooks(
    """
    A list of CreateWebhookInput objects containing the information for creating new Webhook entities. 
    Each object must include the webhook name, event types to subscribe to, and endpoint configuration.
    """
    input: [WebhookCreateInput!]!
  ): [Webhook!]

  """
  Mutation to update one or more existing webhooks.
  """
  updateWebhooks(
    """
    A list of WebhookUpdateInput objects, each containing the ID of the webhook to update and the fields to modify.
    """
    input: [WebhookUpdateInput!]!
  ): [Webhook!]

  """
  Mutation to delete one or more webhooks based on their unique IDs.
  """
  deleteWebhooks(
    """
    A list of IDs representing the webhooks to delete.
    """
    ids: [ID!]!
  ): Boolean!
}

Input Data Types

WebhookCreateInput

"""
Input type for creating a new webhook.
"""
input WebhookCreateInput {
  """
  A name for the webhook, chosen by the user to help identify its purpose.
  """
  name: String!
  
  """
  A list of event types the webhook will subscribe to, such as FLOOR_OCCUPANCY, ROOM_OCCUPANCY, etc.
  """
  event_types: [EventType!]!
  
  """
  Configuration settings for the endpoint where the webhook sends data.
  """
  endpoint_config: EndpointConfigInput!
}

WebhookUpdateInput

"""
Input type for updating an existing webhook.
"""
input WebhookUpdateInput {
  """
  Unique identifier for the webhook to be updated.
  """
  id: ID!
  
  """
  Updated name for the webhook, chosen by the user.
  """
  name: String
  
  """
  Updated list of event types the webhook will subscribe to.
  """
  event_types: [EventType!]
  
  """
  Updated configuration settings for the endpoint.
  """
  endpoint_config: EndpointConfigInput
}

EndpointConfigInput

"""
Input type for endpoint configuration, specifying the webhook destination and authentication settings.
"""
input EndpointConfigInput {
  """
  The URL of the webhook endpoint where events will be sent. Only HTTPS URLs are supported.
  """
  url: String!
  
  """
  The HTTP timeout in seconds for the request to complete. Acceptable values range from 1 to 15.
  """
  http_timeout: Int!
  
  """
  Optional API key configuration for header-based authentication.
  """
  api_key: ApiKeyInput
  
  """
  Optional basic authentication configuration, providing a username and password.
  """
  basic_auth: BasicAuthInput
}

BasicAuthInput

"""
Input type for basic authentication, specifying username and password credentials.
"""
input BasicAuthInput {
  """
  The username for basic authentication.
  """
  username: String!
  
  """
  The password for basic authentication, associated with the username.
  """
  password: String!
}

ApiKeyInput

"""
Input type for API key configuration, defining the API key and the header name to be used.
"""
input ApiKeyInput {
  """
  The header key name to be used for the API key, such as 'x-api-key'.
  """
  key: String!
  
  """
  The actual API key value for authentication.
  """
  value: String!
}

Enums

EventType

"""
Enum representing the different types of events that can be tracked with a webhook.
"""
enum EventType {
  """
  Event type for floor occupancy updates.
  """
  FLOOR_OCCUPANCY

  """
  Event type for room occupancy updates.
  """
  ROOM_OCCUPANCY

  """
  Event type for zone occupancy updates.
  """
  ZONE_OCCUPANCY

  """
  Event type for detection coordinate updates.
  """
  DETECTIONS

  """
  Event type for traffic (enter/exits) updates.
  """
  TRAFFIC
}

Query Data Types

Webhook

"""
Represents a webhook subscription, containing information on the events it tracks and the endpoint configuration.
"""
type Webhook {
  """
  A unique identifier for the webhook subscription.
  """
  id: ID!

  """
  A user-defined name for the webhook, useful for identifying the webhook purpose.
  """
  name: String!

  """
  A list of event types that the webhook subscribes to, such as FLOOR_OCCUPANCY, ROOM_OCCUPANCY, etc.
  """
  event_types: [EventType!]!

  """
  Configuration details for the endpoint, including URL, timeout, and authentication options.
  """
  endpoint_config: EndpointConfig!
}

EndpointConfig

"""
Configuration settings for the endpoint where the webhook sends data.
"""
type EndpointConfig {
  """
  The URL of the webhook endpoint where events will be sent. Only HTTPS URLs are supported.
  """
  url: String!

  """
  The HTTP timeout in seconds for the request to complete. Acceptable values are between 1 and 15.
  """
  http_timeout: Int!

  """
  Optional API key configuration for header-based authentication.
  """
  api_key: ApiKey

  """
  Optional basic authentication configuration, including username and password.
  """
  basic_auth: BasicAuth
}

BasicAuth

"""
A type representing basic authentication configuration.
"""
type BasicAuth {
  """
  The username for basic authentication.
  """
  username: String!

  """
  The password associated with the username for basic authentication.
  """
  password: String!
}

ApiKey

"""
A type representing API credentials.
"""
type ApiKey {
  """
  This key represents the type of header key, often specifying the header name to be used in authentication, such as 'x-api-key'.
  """
  key: String!

  """
  The actual API key value used for authentication in requests.
  """
  value: String!
}