Module: EmailFuse::Webhooks

Defined in:
lib/email_fuse/webhooks.rb

Overview

Examples:

Create a webhook

EmailFuse::Webhooks.create(
  endpoint: "https://webhook.example.com/handler",
  events: ["email.sent", "email.delivered", "email.bounced"]
)

List all webhooks

EmailFuse::Webhooks.list

Retrieve a specific webhook

EmailFuse::Webhooks.get("4dd369bc-aa82-4ff3-97de-514ae3000ee0")

Update a webhook

EmailFuse::Webhooks.update(
  webhook_id: "430eed87-632a-4ea6-90db-0aace67ec228",
  endpoint: "https://new-webhook.example.com/handler",
  events: ["email.sent", "email.delivered"],
  status: "enabled"
)

Delete a webhook

EmailFuse::Webhooks.remove("4dd369bc-aa82-4ff3-97de-514ae3000ee0")

Class Method Summary collapse

Class Method Details

.create(params = {}) ⇒ Hash

Create a new webhook to receive real-time notifications about email events

Examples:

EmailFuse::Webhooks.create(
  endpoint: "https://webhook.example.com/handler",
  events: ["email.sent", "email.delivered", "email.bounced"]
)

Parameters:

  • params (Hash) (defaults to: {}) —

    The webhook parameters

Options Hash (params):

  • :endpoint (String) —

    The URL where webhook events will be sent (required)

  • :events (Array<String>) —

    Array of event types to subscribe to (required)

Returns:

  • (Hash) —

    The webhook object containing id, object type, and signing_secret



50
51
52
53
 
# File 'lib/email_fuse/webhooks.rb', line 50

def create(params = {})
  path = "webhooks"
  EmailFuse::Request.new(path, params, "post").perform
end

.get(webhook_id) ⇒ Hash

Retrieve a single webhook for the authenticated user

Examples:

EmailFuse::Webhooks.get("4dd369bc-aa82-4ff3-97de-514ae3000ee0")

Parameters:

  • webhook_id (String) —

    The webhook ID (required)

Returns:

  • (Hash) —

    The webhook object with full details

Raises:

  • (ArgumentError) 


82
83
84
85
86
87
 
# File 'lib/email_fuse/webhooks.rb', line 82

def get(webhook_id)
  raise ArgumentError, "webhook_id is required" if webhook_id.nil? || webhook_id.to_s.empty?

  path = "webhooks/#{webhook_id}"
  EmailFuse::Request.new(path, {}, "get").perform
end

.list(params = {}) ⇒ Hash

Retrieve a list of webhooks for the authenticated user

Examples:

EmailFuse::Webhooks.list

With pagination

EmailFuse::Webhooks.list(limit: 20, after: "4dd369bc-aa82-4ff3-97de-514ae3000ee0")

Parameters:

  • params (Hash) (defaults to: {}) —

    The pagination parameters

Options Hash (params):

  • :limit (Integer) —

    Number of webhooks to retrieve (max: 100, min: 1)

  • :after (String) —

    The ID after which to retrieve more webhooks (for pagination)

  • :before (String) —

    The ID before which to retrieve more webhooks (for pagination)

Returns:

  • (Hash) —

    A paginated list of webhook objects



69
70
71
72
 
# File 'lib/email_fuse/webhooks.rb', line 69

def list(params = {})
  path = EmailFuse::PaginationHelper.build_paginated_path("webhooks", params)
  EmailFuse::Request.new(path, {}, "get").perform
end

.remove(webhook_id) ⇒ Hash

Remove an existing webhook

Examples:

EmailFuse::Webhooks.remove("4dd369bc-aa82-4ff3-97de-514ae3000ee0")

Parameters:

  • webhook_id (String) —

    The webhook ID (required)

Returns:

  • (Hash) —

    Confirmation object with id, object type, and deleted status

Raises:

  • (ArgumentError) 


123
124
125
126
127
128
 
# File 'lib/email_fuse/webhooks.rb', line 123

def remove(webhook_id)
  raise ArgumentError, "webhook_id is required" if webhook_id.nil? || webhook_id.to_s.empty?

  path = "webhooks/#{webhook_id}"
  EmailFuse::Request.new(path, {}, "delete").perform
end

.update(params = {}) ⇒ Hash

Update an existing webhook configuration

Examples:

EmailFuse::Webhooks.update(
  webhook_id: "430eed87-632a-4ea6-90db-0aace67ec228",
  endpoint: "https://new-webhook.example.com/handler",
  events: ["email.sent", "email.delivered"],
  status: "enabled"
)

Parameters:

  • params (Hash) (defaults to: {}) —

    The webhook update parameters

Options Hash (params):

  • :webhook_id (String) —

    The webhook ID (required)

  • :endpoint (String) —

    The URL where webhook events will be sent

  • :events (Array<String>) —

    Array of event types to subscribe to

  • :status (String) —

    The webhook status (“enabled” or “disabled”)

Returns:

  • (Hash) —

    The updated webhook object

Raises:

  • (ArgumentError) 


106
107
108
109
110
111
112
113
 
# File 'lib/email_fuse/webhooks.rb', line 106

def update(params = {})
  params = params.dup # Don't mutate caller's hash
  webhook_id = params.delete(:webhook_id)
  raise ArgumentError, ":webhook_id is required" if webhook_id.nil? || webhook_id.to_s.empty?

  path = "webhooks/#{webhook_id}"
  EmailFuse::Request.new(path, params, "patch").perform
end

.verify(params = {}) ⇒ Boolean

Verify a webhook payload using HMAC-SHA256 signature validation This validates that the webhook request came from EmailFuse and hasn’t been tampered with

Examples:

EmailFuse::Webhooks.verify(
  payload: request.body.read,
  headers: {
    svix_id: "id_1234567890abcdefghijklmnopqrstuvwxyz",
    svix_timestamp: "1616161616",
    svix_signature: "v1,signature_here"
  },
  webhook_secret: "whsec_1234567890abcdez"
)

Parameters:

  • params (Hash) (defaults to: {}) —

    The webhook verification parameters

Options Hash (params):

  • :payload (String) —

    The raw webhook payload body (required)

  • :headers (Hash) —

    The webhook headers containing svix-id, svix-timestamp, and svix-signature (required)

  • :webhook_secret (String) —

    The signing secret from webhook creation (required)

Returns:

  • (Boolean) —

    true if verification succeeds

Raises:

  • (StandardError) —

    If verification fails or required parameters are missing



152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/email_fuse/webhooks.rb', line 152

def verify(params = {})
  payload = params[:payload]
  headers = params[:headers] || {}
  webhook_secret = params[:webhook_secret]

  validate_required_params(payload, headers, webhook_secret)
  validate_timestamp(headers[:svix_timestamp])

  signed_content = "#{headers[:svix_id]}.#{headers[:svix_timestamp]}.#{payload}"
  decoded_secret = decode_secret(webhook_secret)
  expected_signature = generate_signature(decoded_secret, signed_content)

  verify_signature(headers[:svix_signature], expected_signature)
end