Webhook notifications

The Pearl API allows you to use webhooks to receive real-time updates when AI completions or Expert responses are ready. The below endpoints let you set up and update webhook URLs to receive real-time updates.

Register a WebhookCopied!

This endpoint registers a new webhook URL for communication events.

Endpoint

POST /api/v1/webhook

Request Headers

Request Body

{
    "endpoint": "https://example.com/webhook"
}

Response

Success (200 OK)

HTTP/1.1 200 OK

Error Responses

Update a WebhookCopied!

This endpoint updates the registered webhook URL.

Endpoint

PUT /api/v1/webhook

Request Headers

Request Body

{
    "endpoint": "https://example.com/new-webhook"
}

Response

Success (200 OK)

HTTP/1.1 200 OK

Error Responses

Python Example: Calling the API

import requests

# Base URL
BASE_URL = "https://api.pearl.com/api/v1/webhook"

# API Key
API_KEY = "YOUR_PEARL_API_KEY"

# Example webhook URL
webhook_url = "https://example.com/webhook"

# Headers
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

# Register a new webhook
def register_webhook(endpoint):
    url = BASE_URL
    data = {"endpoint": endpoint}
    response = requests.post(url, json=data, headers=HEADERS)

    if response.status_code == 200:
        print("Webhook registered successfully!")
    else:
        print(f"Error: {response.status_code} - {response.json()}")

# Update an existing webhook
def update_webhook(new_endpoint):
    url = BASE_URL
    data = {"endpoint": new_endpoint}
    response = requests.put(url, json=data, headers=HEADERS)

    if response.status_code == 200:
        print("Webhook updated successfully!")
    else:
        print(f"Error: {response.status_code} - {response.json()}")

# Example usage
register_webhook("https://example.com/webhook")
update_webhook("https://example.com/new-webhook")

Securing webhooks: verifying signature authenticityCopied!

Pearl API will use your secret Api Key to create a hash signature that's sent to you with each payload. The hash signature will appear in each delivery as the value of the below header:

X-Pearl-API-Signature: <computed-signature>

This signature is a cryptographic hash generated using an HMAC-SHA1 function. Your API key is the secret, and the request payload (serialized JSON) serves as the message. The resulting hash is Base64-encoded and sent with the request.

Validating the signature, you can ensure the data integrity (the message was not altered in transit) and authenticate the sender (only Pearl API has the necessary secret key).

Webhook payload

Each webhook request contains a JSON body with the following structure:

{
  "sessionId": "abc123",
  "message": "Hello, I can help you with that.",
  "messageDateTime": "2024-03-13T12:45:00Z",
  "expert": {
    "name": "Dr. Sarah Johnson",
    "jobDescription": "Veterinarian specializing in feline health",
    "avatarUrl": "https://example.com/avatars/sarah_johnson.png"
  }
}

• sessionId → Chat session identifier, the one that was passed on the initial request to chat/completions.

• message → Message content sent by the human Expert or Pearl AI.

• messageDateTime → Timestamp when the message was sent.

• expert → Contains details about the expert.

Signature verification

To verify the authenticity of a webhook request, you should:

1. Convert incoming JSON payload into string.

2. Generate hash string using your Api Key.

3. Sign the payload string with HMAC-SHA1 using generated hash string from the previous step.

4. Base64 encodes the resulting hash value.

5. Compare the computed signature with the received signature in the X-Pearl-API-Signature header.

   1. If they're equal then this request has passed validation.

   2. If these values do not match, then this request may have been tampered with in-transit or someone may be spoofing requests to your endpoint.

Basic Verification Example (Python)

import hmac
import hashlib
import base64

def verify_signature(secret, payload, received_signature):
    secret_hash = hashlib.sha256(f"{secret}:reference_token".encode()).digest().hex().upper()
    computed_hash = hmac.new(secret_hash.encode(), payload.encode(), hashlib.sha1).digest()
    computed_signature = base64.b64encode(computed_hash).decode()
    return computed_signature == received_signature

# Example usage
secret_key = "your_api_key"
request_body = '{"sessionId":"abc123","message":"Hello"}'
received_signature = "base64_encoded_hash_from_header"

if verify_signature(secret_key, request_body, received_signature):
    print("Valid webhook request")
else:
    print("Invalid signature, reject request")