Authentication

To ensure secure communication, Buzzeasy uses an API key for authentication on all webhook events. This API key needs to be provided by you and configured in the Buzzeasy portal.

1. Fill Up the API Key Field: Log in to the Buzzeasy portal and navigate to the Service Hooks section (Integration / Service Hooks). Here, you'll find a field to enter your API key. This key is a secret that you generate on your end.
2. Validate Incoming HTTP Callback: When Buzzeasy sends a webhook event to your application, it includes the API key in the x-api-key header. Your application should validate this header to ensure that the request is coming from Buzzeasy.

Remember, the API key is sensitive information. Always use secure methods to generate, store, and use your API key.

Webhook Event Setup

Once authentication is set up, you can start configuring webhook events in the Buzzeasy portal.

1. Provide a Callback URL: For each event that you want to listen to, provide a callback URL. This is the URL of your application endpoint that will receive the HTTP POST requests from Buzzeasy when the event occurs.
2. Enable the Event: Use the toggle button next to each event to enable or disable it. When an event is enabled, Buzzeasy will send an HTTP POST request to the provided callback URL whenever the event occurs.
3. Download Request Body Schema: To understand the structure of the data sent by Buzzeasy, you can download the request body schema. Click the download button at the end of the specific event line in the table. This will give you a file, detailing the structure of the JSON data sent by Buzzeasy for that event.

Event Schema example:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "examples": [
    {
      "id": "ff34b1fb68cd4f7f9921e70c08fab7a7",
      "mediaType": "Webchat",
      "isOutbound": true,
      "createdAt": "2022-03-08T07:39:47.6052457Z",
      "closedAt": "2022-03-08T07:41:47.6052457Z",
      "agent": {
        "id": "638858857ff57ad8637a7528",
        "name": "Agent John",
        "email": "john@agent.com",
        "phone": "+123456789"
      },
      "customerIdentifier": "+123456789",
      "customerId": "6d820576a3864160a715312b4e9ac376",
      "primaryConversationId": "48fad19d15104c8fbd7344853f35019e",
      "completionCode": "Success",
      "notes": "Job well done",
      "result": "Handled"
    }
  ],
  "required": [
    "id",
    "mediaType",
    "isOutbound",
    "createdAt",
    "closedAt",
    "agent",
    "result"
  ],
  "title": "Work item schema",
  "type": "object",
  "properties": {
    "id": {
      "$id": "#/properties/id",
      "examples": [
        "ff34b1fb68cd4f7f9921e70c08fab7a7"
      ],
      "title": "Work item id",
      "description": "Unique identifier of the work item",
      "type": "string"
    },
    "mediaType": {
      "$id": "#/properties/mediaType",
      "examples": [
        "Voice",
        "Email",
        "Webchat",
        "Messaging",
        "Lookup"
      ],
      "title": "Media type",
      "description": "Possible values: Voice | Email | Webchat | Messaging | Lookup",
      "type": "string"
    },
    "isOutbound": {
      "$id": "#/properties/isOutbound",
      "examples": [
        true,
        false
      ],
      "title": "Is outbound",
      "type": "boolean"
    },
    "createdAt": {
      "$id": "#/properties/createdAt",
      "examples": [
        "2022-03-08T07:39:47.6052457Z"
      ],
      "title": "Work item creation time",
      "description": "Defined in UTC ISO 8601 format",
      "type": "string"
    },
    "closedAt": {
      "$id": "#/properties/closedAt",
      "examples": [
        "2022-03-08T07:39:47.6052457Z"
      ],
      "title": "Work item close time",
      "description": "Defined in UTC ISO 8601 format",
      "type": "string"
    },
    "customerIdentifier": {
      "$id": "#/properties/customerIdentifier",
      "examples": [
        "john.doe@mailserv.com"
      ],
      "title": "Customer identifier",
      "description": "Phone number or email address",
      "type": "string"
    },
    "customerId": {
      "$id": "#/properties/customerId",
      "examples": [
        "6d820576a3864160a715312b4e9ac376"
      ],
      "title": "Customer id",
      "description": "Unique identifier of the customer in Buzzeasy",
      "type": "string"
    },
    "primaryConversationId": {
      "$id": "#/properties/primaryConversationId",
      "examples": [
        "48fad19d15104c8fbd7344853f35019e"
      ],
      "title": "Primary conversation id",
      "description": "Unique identifier of the conversation which triggered the work item",
      "type": "string"
    },
    "completionCode": {
      "$id": "#/properties/completionCode",
      "examples": [
        "Success"
      ],
      "title": "Work item completion code",
      "description": "Result code selected by the agent",
      "type": "string"
    },
    "notes": {
      "$id": "#/properties/notes",
      "examples": [
        "Job well done"
      ],
      "title": "Work item notes",
      "description": "Notes provided by the agent",
      "type": "string"
    },
    "agent": {
      "$id": "#/properties/agent",
      "examples": [
        {
          "id": "638858857ff57ad8637a7528",
          "name": "Agent John",
          "email": "john@agent.com",
          "phone": "+123456789"
        }
      ],
      "title": "Agent schema",
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "$id": "#/properties/agent/id",
          "examples": [
            "638858857ff57ad8637a7528"
          ],
          "title": "Agent identifier",
          "description": "Unique identifier of the agent",
          "type": "string"
        },
        "name": {
          "$id": "#/properties/agent/name",
          "examples": [
            "Agent John"
          ],
          "title": "Agent name",
          "type": "string"
        },
        "email": {
          "$id": "#/properties/agent/email",
          "examples": [
            "john@agent.com"
          ],
          "title": "Agent mail address",
          "type": "string"
        },
        "phone": {
          "$id": "#/properties/agent/phone",
          "examples": [
            "+123456789"
          ],
          "title": "Agent phone number",
          "type": "string"
        }
      }
    },
    "result": {
      "$id": "#/properties/result",
      "examples": [
        "Handled",
        "Abandoned",
        "Missed",
        "Failed",
        "Cancelled",
        "Rejected"
      ],
      "title": "Work item result",
      "description": "The result defined by the system",
      "type": "string"
    }
  },
  "additionalProperties": false
}