Skip to main content

List endpoints

result = client.webhooks.list
result.data  # => Array of Webhook objects

Create an endpoint

webhook = client.webhooks.create(
  url:    "https://yourapp.com/webhooks/whatsrb",
  events: ["message.received", "message.status", "message.failed"]
)

webhook.id      # => 1
webhook.url     # => "https://yourapp.com/webhooks/whatsrb"
webhook.events  # => ["message.received", "message.status", "message.failed"]
webhook.secret  # => "whsec_xxx"  — only present on create, store it now!
webhook.active? # => true
Passing no events subscribes to all events.

Retrieve an endpoint

webhook = client.webhooks.retrieve(1)

Update an endpoint

webhook = client.webhooks.update(1,
  url:    "https://yourapp.com/new-path",
  active: false,
  events: ["message.failed"]
)

Delete an endpoint

client.webhooks.delete(1)  # => true

Verify incoming signatures

Every webhook request includes X-Webhook-Signature and X-Webhook-Event headers. Verify the signature before processing.

Quick method (Rack/Rails)

# Handles body reading, rewinding, and header extraction automatically
WhatsrbCloud::WebhookSignature.verify_request(request, secret: ENV["WHATSRB_WEBHOOK_SECRET"])

Manual method

WhatsrbCloud::WebhookSignature.verify?(
  payload: request.body.read,
  signature: request.headers["X-Webhook-Signature"],
  secret: ENV["WHATSRB_WEBHOOK_SECRET"]
)

Full Rails example

class WebhooksController < ApplicationController
  skip_forgery_protection

  def create
    unless WhatsrbCloud::WebhookSignature.verify_request(request, secret: webhook_secret)
      return head :unauthorized
    end

    Rails.application.config.event_registry.dispatch(payload)
    head :ok
  end

  private

  def payload = @payload ||= JSON.parse(request.body.read)
  def webhook_secret = ENV["WHATSRB_WEBHOOK_SECRET"]
end
The signature format is sha256=<HMAC-SHA256(secret, raw_body)>.
For routing events to handlers, see Registries.

Webhook attributes

AttributeTypeDescription
idIntegerEndpoint ID
urlStringYour HTTPS endpoint URL
eventsArraySubscribed event types
active?BooleanWhether endpoint is active
secretStringSigning secret (only on create)

Supported events

EventWhen
message.receivedInbound message received
message.statusMessage status updated
message.failedMessage failed to send
session.connectedSession connected
session.disconnectedSession disconnected
session.failedSession connection failed
quota.warningApproaching daily quota
quota.exceededDaily quota exceeded
agent_run.completedAgent run finished successfully
agent_run.failedAgent run failed