botserver/docs/src/chapter-06-gbdialog/keyword-webhook.md

WEBHOOK

Creates an instant HTTP endpoint for your bot. With WEBHOOK, you can expose any BASIC script as an API endpoint that external systems can call - perfect for integrations, notifications, and building custom APIs with LLM-powered responses.

Why WEBHOOK?

Traditional API development requires:

• Setting up a web framework
• Writing routing code
• Handling HTTP parsing
• Deploying infrastructure

With General Bots WEBHOOK, you write one line and your endpoint is live:

WEBHOOK "my-endpoint"

That's it. Your script is now accessible at /api/{botname}/webhook/my-endpoint.

Syntax

WEBHOOK "endpoint-name"

Parameters

Parameter	Type	Description
endpoint-name	String	Unique name for the webhook (alphanumeric, hyphens, underscores)

Request Data Available

When your webhook is called, these variables are automatically available:

Variable	Description	Example
params	Query string parameters	params.id, params.filter
body	JSON request body as object	body.customer.name
headers	HTTP headers	headers.authorization
method	HTTP method used	"POST", "GET"
path	Request path	"/webhook/my-endpoint"

Examples

1. Simple Status Endpoint

' status.bas - Simple health check
WEBHOOK "status"

result_status = "healthy"
result_timestamp = NOW()
result_version = "1.0.0"

Call it:

curl https://bot.example.com/api/mybot/webhook/status

Response:

{"status": "healthy", "timestamp": "2024-01-20T10:30:00Z", "version": "1.0.0"}

2. WhatsApp Order Notification

Send order confirmations directly to customers on WhatsApp:

' order-notify.bas - Notify customer via WhatsApp
WEBHOOK "order-notify"

order_id = body.order_id
customer_phone = body.customer_phone
customer_name = body.customer_name
total = body.total
items = body.items

IF order_id = "" OR customer_phone = "" THEN
    result_status = 400
    result_error = "Missing order_id or customer_phone"
    EXIT
END IF

' Build order summary
order_summary = "🛒 *Order Confirmed #" + order_id + "*\n\n"
order_summary = order_summary + "Hi " + customer_name + "!\n\n"
order_summary = order_summary + "Your order has been confirmed.\n"
order_summary = order_summary + "Total: $" + total + "\n\n"
order_summary = order_summary + "We'll notify you when it ships!"

' Send to WhatsApp using TALK TO
TALK TO "whatsapp:" + customer_phone, order_summary

' Save order to database
order_status = "confirmed"
created_at = NOW()
SAVE "orders", order_id, customer_name, customer_phone, total, order_status, created_at

result_status = "ok"
result_order_id = order_id
result_message = "Customer notified via WhatsApp"

Call it:

curl -X POST https://bot.example.com/api/mybot/webhook/order-notify \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-12345",
    "customer_phone": "+5511999887766",
    "customer_name": "João",
    "total": "299.90",
    "items": ["Widget", "Gadget"]
  }'

3. WhatsApp Document Delivery

Send invoices, reports, or documents to WhatsApp:

' send-invoice.bas - Generate and send invoice via WhatsApp
WEBHOOK "send-invoice"

order_id = body.order_id
customer_phone = body.customer_phone
customer_name = body.customer_name

IF order_id = "" OR customer_phone = "" THEN
    result_status = 400
    result_error = "Missing order_id or customer_phone"
    EXIT
END IF

' Get order data
order = FIND "orders", "order_id=" + order_id

' Generate PDF invoice
invoice_date = FORMAT(NOW(), "DD/MM/YYYY")
GENERATE PDF "templates/invoice.html", order_id, customer_name, order.total, order.items, invoice_date, "invoices/" + order_id + ".pdf"

' Send PDF to WhatsApp with caption
SEND FILE TO "whatsapp:" + customer_phone, "invoices/" + order_id + ".pdf", "📄 Invoice #" + order_id + " - Thank you for your purchase!"

' Also send a follow-up message
TALK TO "whatsapp:" + customer_phone, "If you have any questions about your order, just reply to this message! 😊"

result_status = "ok"
result_message = "Invoice sent to WhatsApp"

4. WhatsApp Support Ticket System

Create support tickets and notify via WhatsApp:

' support-ticket.bas - Create ticket and notify customer
WEBHOOK "support-ticket"

customer_phone = body.phone
customer_name = body.name
issue = body.issue
priority = body.priority

IF customer_phone = "" OR issue = "" THEN
    result_status = 400
    result_error = "Missing phone or issue description"
    EXIT
END IF

IF priority = "" THEN
    priority = "normal"
END IF

' Create ticket
ticket_id = "TKT-" + FORMAT(NOW(), "YYYYMMDDHHmmss")
ticket_status = "open"
created_at = NOW()

SAVE "support_tickets", ticket_id, customer_name, customer_phone, issue, priority, ticket_status, created_at

' Notify customer via WhatsApp
confirmation = "🎫 *Support Ticket Created*\n\n"
confirmation = confirmation + "Ticket: #" + ticket_id + "\n"
confirmation = confirmation + "Priority: " + priority + "\n\n"
confirmation = confirmation + "We received your request:\n_" + issue + "_\n\n"
confirmation = confirmation + "Our team will respond within 24 hours."

TALK TO "whatsapp:" + customer_phone, confirmation

' Notify support team
team_msg = "🆕 New ticket #" + ticket_id + "\n"
team_msg = team_msg + "From: " + customer_name + " (" + customer_phone + ")\n"
team_msg = team_msg + "Priority: " + priority + "\n"
team_msg = team_msg + "Issue: " + issue

TALK TO "whatsapp:+5511999000001", team_msg

result_status = "ok"
result_ticket_id = ticket_id

5. AI-Powered WhatsApp Assistant

Create an API that uses AI and responds via WhatsApp:

' ai-assistant.bas - AI assistant that responds via WhatsApp
WEBHOOK "ask-ai"

question = body.question
customer_phone = body.phone
context_type = body.context

IF question = "" OR customer_phone = "" THEN
    result_status = 400
    result_error = "Missing question or phone"
    EXIT
END IF

' Load appropriate knowledge base
IF context_type = "products" THEN
    USE KB "product-catalog"
ELSE IF context_type = "support" THEN
    USE KB "support-docs"
ELSE
    USE KB "general-faq"
END IF

' Set AI context
SET CONTEXT "You are a helpful assistant. Be concise and friendly. Use emojis occasionally."

' Get AI response
answer = LLM question

' Send response via WhatsApp
TALK TO "whatsapp:" + customer_phone, answer

' Log the interaction
log_question = question
log_answer = answer
log_phone = customer_phone
log_context = context_type
log_timestamp = NOW()

INSERT "ai_conversations", log_question, log_answer, log_phone, log_context, log_timestamp

result_status = "ok"
result_answer = answer

6. WhatsApp Broadcast for Promotions

Send promotional messages to multiple customers:

' promo-broadcast.bas - Send promotions to customer list
WEBHOOK "send-promo"

promo_title = body.title
promo_message = body.message
promo_image = body.image_url
customer_segment = body.segment

IF promo_message = "" THEN
    result_status = 400
    result_error = "Missing promotion message"
    EXIT
END IF

IF customer_segment = "" THEN
    customer_segment = "all"
END IF

' Get customers for this segment
customers = FIND "customers", "segment=" + customer_segment + " AND whatsapp_optin=true"

sent_count = 0
error_count = 0

' Build promo message with formatting
full_message = "🎉 *" + promo_title + "*\n\n"
full_message = full_message + promo_message + "\n\n"
full_message = full_message + "_Reply STOP to unsubscribe_"

FOR EACH customer IN customers
    ' Send to each customer
    IF promo_image <> "" THEN
        SEND FILE TO "whatsapp:" + customer.phone, promo_image, full_message
    ELSE
        TALK TO "whatsapp:" + customer.phone, full_message
    END IF
    
    sent_count = sent_count + 1
    
    ' Rate limiting - wait between messages
    WAIT 1
NEXT customer

' Log the campaign
campaign_id = "CAMP-" + FORMAT(NOW(), "YYYYMMDDHHmmss")
campaign_title = promo_title
campaign_sent = sent_count
campaign_date = NOW()

INSERT "campaigns", campaign_id, campaign_title, campaign_sent, customer_segment, campaign_date

result_status = "ok"
result_campaign_id = campaign_id
result_sent = sent_count

7. Payment Notification with WhatsApp Receipt

Handle payment webhooks and notify customers:

' payment-webhook.bas - Handle payment and notify via WhatsApp
WEBHOOK "payment"

event_type = body.type
payment_id = body.data.object.id
amount = body.data.object.amount
customer_id = body.data.object.customer

SELECT CASE event_type
    CASE "payment_intent.succeeded"
        ' Get customer info
        customer = FIND "customers", "stripe_id=" + customer_id
        
        ' Update order status
        order_status = "paid"
        paid_at = NOW()
        UPDATE "orders", "payment_id=" + payment_id, order_status, paid_at
        
        ' Format amount (cents to dollars)
        amount_formatted = amount / 100
        
        ' Send WhatsApp receipt
        receipt = "✅ *Payment Received*\n\n"
        receipt = receipt + "Amount: $" + amount_formatted + "\n"
        receipt = receipt + "Payment ID: " + payment_id + "\n"
        receipt = receipt + "Date: " + FORMAT(NOW(), "DD/MM/YYYY HH:mm") + "\n\n"
        receipt = receipt + "Thank you for your purchase! 🙏"
        
        TALK TO "whatsapp:" + customer.phone, receipt
        
    CASE "payment_intent.payment_failed"
        customer = FIND "customers", "stripe_id=" + customer_id
        
        ' Notify customer of failure
        failure_msg = "⚠️ *Payment Failed*\n\n"
        failure_msg = failure_msg + "We couldn't process your payment.\n"
        failure_msg = failure_msg + "Please try again or use a different payment method.\n\n"
        failure_msg = failure_msg + "Need help? Reply to this message!"
        
        TALK TO "whatsapp:" + customer.phone, failure_msg
        
    CASE ELSE
        ' Log unhandled event
        TALK "Unhandled payment event: " + event_type
END SELECT

result_received = TRUE

8. Appointment Reminder System

Webhook to trigger appointment reminders:

' appointment-reminder.bas - Send appointment reminders via WhatsApp
WEBHOOK "send-reminder"

appointment_id = body.appointment_id
hours_before = body.hours_before

IF appointment_id = "" THEN
    result_status = 400
    result_error = "Missing appointment_id"
    EXIT
END IF

IF hours_before = "" THEN
    hours_before = 24
END IF

' Get appointment details
appointment = FIND "appointments", "id=" + appointment_id

' Format date/time nicely
appt_date = FORMAT(appointment.datetime, "dddd, MMMM DD")
appt_time = FORMAT(appointment.datetime, "HH:mm")

' Build reminder message
reminder = "📅 *Appointment Reminder*\n\n"
reminder = reminder + "Hi " + appointment.customer_name + "!\n\n"
reminder = reminder + "This is a reminder of your upcoming appointment:\n\n"
reminder = reminder + "📍 *" + appointment.service + "*\n"
reminder = reminder + "🗓️ " + appt_date + "\n"
reminder = reminder + "🕐 " + appt_time + "\n"
reminder = reminder + "📌 " + appointment.location + "\n\n"
reminder = reminder + "Reply *CONFIRM* to confirm or *CANCEL* to cancel."

' Send via WhatsApp
TALK TO "whatsapp:" + appointment.customer_phone, reminder

' Update reminder sent status
reminder_sent_at = NOW()
UPDATE "appointments", "id=" + appointment_id, reminder_sent_at

result_status = "ok"
result_message = "Reminder sent"

9. Form Submission with WhatsApp Follow-up

Handle web form submissions and follow up on WhatsApp:

' contact-form.bas - Handle contact form and follow up via WhatsApp
WEBHOOK "contact"

name = body.name
email = body.email
phone = body.phone
message = body.message
source = body.source

IF name = "" OR message = "" THEN
    result_status = 400
    result_error = "Name and message are required"
    EXIT
END IF

' Use AI to categorize and generate response
SET CONTEXT "Categorize this message as: sales, support, feedback, or other. Then write a friendly acknowledgment."

ai_prompt = "Customer: " + name + "\nMessage: " + message
ai_response = LLM ai_prompt

' Save the submission
submission_id = "SUB-" + FORMAT(NOW(), "YYYYMMDDHHmmss")
submission_status = "new"
created_at = NOW()

SAVE "submissions", submission_id, name, email, phone, message, source, ai_response, submission_status, created_at

' If phone provided, send WhatsApp confirmation
IF phone <> "" THEN
    whatsapp_msg = "👋 Hi " + name + "!\n\n"
    whatsapp_msg = whatsapp_msg + "Thanks for reaching out! We received your message:\n\n"
    whatsapp_msg = whatsapp_msg + "_" + message + "_\n\n"
    whatsapp_msg = whatsapp_msg + "We'll get back to you soon. In the meantime, feel free to reply here if you have any questions!"
    
    TALK TO "whatsapp:" + phone, whatsapp_msg
END IF

' Send email confirmation too
IF email <> "" THEN
    SEND MAIL email, "We received your message", "Hi " + name + ",\n\nThank you for contacting us. We'll respond within 24 hours.\n\nBest regards"
END IF

result_status = "ok"
result_submission_id = submission_id

10. Multi-Channel Notification Hub

Single webhook that routes to multiple channels:

' notify.bas - Multi-channel notification hub
WEBHOOK "notify"

channel = body.channel
recipient = body.recipient
message = body.message
file_url = body.file
caption = body.caption

IF recipient = "" OR message = "" THEN
    result_status = 400
    result_error = "Missing recipient or message"
    EXIT
END IF

IF channel = "" THEN
    channel = "whatsapp"
END IF

' Route to appropriate channel
SELECT CASE channel
    CASE "whatsapp"
        IF file_url <> "" THEN
            SEND FILE TO "whatsapp:" + recipient, file_url, caption
        ELSE
            TALK TO "whatsapp:" + recipient, message
        END IF
        
    CASE "email"
        subject = body.subject
        IF subject = "" THEN
            subject = "Notification"
        END IF
        
        IF file_url <> "" THEN
            SEND MAIL recipient, subject, message, file_url
        ELSE
            SEND MAIL recipient, subject, message
        END IF
        
    CASE "teams"
        TALK TO "teams:" + recipient, message
        
    CASE "web"
        ' Send to web session
        TALK TO "web:" + recipient, message
        
    CASE ELSE
        result_status = 400
        result_error = "Unknown channel: " + channel
        EXIT
END SELECT

' Log notification
log_channel = channel
log_recipient = recipient
log_message = message
log_timestamp = NOW()

INSERT "notification_log", log_channel, log_recipient, log_message, log_timestamp

result_status = "ok"
result_channel = channel
result_delivered = TRUE

Response Handling

Control the HTTP response by setting result_ prefixed variables:

Simple Response

result_status = "ok"
result_data = my_data

Custom Status Code

result_status = 201  ' Created
result_id = new_id
result_created = TRUE

Error Response

result_status = 400
result_error = "Invalid request"
result_details = "Missing required field: phone"

WhatsApp Message Formatting

WhatsApp supports rich text formatting:

Format	Syntax	Example
Bold	*text*	*Important*
Italic	_text_	_note_
Strikethrough	~text~	~old price~
Monospace	`text`	`code`
Line break	\n	"Line 1\nLine 2"

Example with Formatting

message = "🎉 *Order Confirmed!*\n\n"
message = message + "Order: #" + order_id + "\n"
message = message + "Total: ~$" + old_price + "~ *$" + new_price + "*\n"
message = message + "_Discount applied!_"

TALK TO "whatsapp:" + phone, message

Security Best Practices

1. Validate Webhook Signatures

WEBHOOK "secure-endpoint"

signature = headers.x_webhook_signature
secret = GET BOT MEMORY "webhook_secret"

IF signature = "" THEN
    TALK "Invalid request - no signature"
    result_status = 401
    result_error = "Missing signature"
    EXIT
END IF

' Continue with verified request...

2. Validate Phone Numbers

phone = body.phone

' Remove non-numeric characters
clean_phone = REPLACE(phone, "+", "")
clean_phone = REPLACE(clean_phone, "-", "")
clean_phone = REPLACE(clean_phone, " ", "")

IF LEN(clean_phone) < 10 THEN
    result_status = 400
    result_error = "Invalid phone number"
    EXIT
END IF

' Add country code if missing
IF LEFT(clean_phone, 2) <> "55" THEN
    clean_phone = "55" + clean_phone
END IF

TALK TO "whatsapp:+" + clean_phone, message

3. Rate Limiting

WEBHOOK "rate-limited"

client_ip = headers.x_forwarded_for
rate_key = "rate:" + client_ip
current_count = GET BOT MEMORY rate_key

IF current_count = "" THEN
    current_count = 0
END IF

IF current_count > 100 THEN
    result_status = 429
    result_error = "Rate limit exceeded"
    result_retry_after = 60
    EXIT
END IF

SET BOT MEMORY rate_key, current_count + 1
' Process request...

Use Cases Summary

Use Case	Webhook Name	Description
Order Notifications	/order-notify	Confirm orders via WhatsApp
Invoice Delivery	/send-invoice	Send PDF invoices to WhatsApp
Support Tickets	/support-ticket	Create tickets, notify via WhatsApp
AI Assistant	/ask-ai	LLM answers sent to WhatsApp
Promotions	/send-promo	Broadcast promos to customers
Payment Alerts	/payment	Payment receipts via WhatsApp
Reminders	/send-reminder	Appointment reminders
Contact Forms	/contact	Form follow-up on WhatsApp
Multi-Channel	/notify	Route to any channel

Technical Notes

• Webhooks register during script compilation
• Stored in system_automations table with kind = Webhook
• Endpoint names must be unique per bot
• Request timeout: 30 seconds (keep processing fast)
• Maximum request body: 10MB
• HTTPS required in production

See Also

• TALK TO - Send messages to specific recipients
• SEND FILE TO - Send files to recipients
• SET SCHEDULE - Time-based automation
• ON - Database trigger events
• LLM - Language model queries
• USE KB - Knowledge base integration