Create Webhooks

Create one or more new webhooks with specified configurations.

Users can subscribe only once to each event type (Detections, Traffic, Floor Occupancy, Room Occupancy, and Zone Occupancy).

Event ordering is not guaranteed. Prioritizing speed, we deliver events as received. Use event timestamps for ordering and implement idempotent processing to handle potential out-of-order or duplicate events.

First, obtain an access token to get started here.

Create one or more new webhooks to receive real-time updates on Butlr platform events. Specify the webhook name, event types, endpoint URL and authentication details in the WebhookInput object. Upon successful creation, the mutation returns the newly created webhook(s) with their unique IDs.

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!]
}

"""
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.
  """
  eventTypes: [EventType!]!
  
  """
  Configuration settings for the endpoint where the webhook sends data.
  """
  endpointConfig: EndpointConfigInput!
}

"""
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
}

"""
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
}

"""
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!
}

"""
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!
}

"""
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!
}

"""
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!
}

"""
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
}

"""
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!
}

Mutation

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

#variables
{
  "input": [{
      "name": "My Webhook",
      "event_types": ["FLOOR_OCCUPANCY"],
      "endpoint_config": {
        "url": "https://customer.api.com/webhooks",
        "http_timeout": 10,
        "api_key": {
          "key": "x-api-key",
          "value": "akfsdl;jf;alksjdfiuhwiefhsks"
        },
        "basic_auth": {
          "username": "bob",
          "password": "letmein"
        }
      }
    },
    {
      "name": "Another Webhook",
      "event_types": ["ROOM_OCCUPANCY", "DETECTIONS"],
      "endpoint_config": {
        "url": "https://another.customer.api.com/webhooks",
        "http_timeout": 15
      }
    }]
}

Response (Example)

{
  "data": {
    "createWebhooks": [
      {
        "id": "webhook_2oqujQF2pRZO8BqPgT8dWkf4Swb",
        "name": "My Webhook",
        "event_types": ["FLOOR_OCCUPANCY"],
        "endpoint_config": {
          "url": "https://customer.api.com/webhooks",
          "http_timeout": 10,
          "api_key": {
            "key": "x-api-key",
            "value": "akfsdl;jf;alksjdfiuhwiefhsks"
          },
          "basic_auth": {
            "username": "bob",
            "password": "letmein"
          }
        }
      },
      {
        "id": "webhook_2oqujRtbTdX1KTA0olXvAtftGWA",
        "name": "Another Webhook",
        "event_types": ["ROOM_OCCUPANCY", "DETECTIONS"],
        "endpoint_config": {
          "url": "https://another.customer.api.com/webhooks",
          "http_timeout": 15,
          "api_key": null,
          "basic_auth": null
        }
      }
    ]
  }
}