Module: Resend::Webhooks

Defined in:
lib/resend/webhooks.rb

Overview

Examples:

Create a webhook

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

List all webhooks

Resend::Webhooks.list

Retrieve a specific webhook

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

Update a webhook

Resend::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

Resend::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:

Resend::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/resend/webhooks.rb', line 50

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

.get(webhook_id = "") ⇒ Hash

Retrieve a single webhook for the authenticated user

Examples:

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

Parameters:

  • webhook_id (String) (defaults to: "") —

    The webhook ID

Returns:

  • (Hash) —

    The webhook object with full details



82
83
84
85
 
# File 'lib/resend/webhooks.rb', line 82

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

.get_event(webhook_id, event_id) ⇒ Hash

Retrieve a webhook event

Examples:

Resend::Webhooks.get_event("4dd369bc-aa82-4ff3-97de-514ae3000ee0", "msg_123")

Parameters:

  • webhook_id (String) —

    The webhook ID

  • event_id (String) —

    The webhook event ID

Returns:

  • (Hash) —

    The webhook event with full details



115
116
117
118
 
# File 'lib/resend/webhooks.rb', line 115

def get_event(webhook_id, event_id)
  path = "webhooks/#{webhook_id}/events/#{event_id}"
  Resend::Request.new(path, {}, "get").perform
end

.list(params = {}) ⇒ Hash

Retrieve a list of webhooks for the authenticated user

Examples:

Resend::Webhooks.list

With pagination

Resend::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/resend/webhooks.rb', line 69

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

.list_event_attempts(webhook_id, event_id, params = {}) ⇒ Hash

Retrieve delivery attempts for a webhook event

Examples:

Resend::Webhooks.list_event_attempts("4dd369bc-aa82-4ff3-97de-514ae3000ee0", "msg_123")

With pagination

Resend::Webhooks.list_event_attempts(
  "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
  "msg_123",
  limit: 20,
  after: "atmpt_123"
)

Parameters:

  • webhook_id (String) —

    The webhook ID

  • event_id (String) —

    The webhook event ID

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

    The pagination parameters

Options Hash (params):

  • :limit (Integer) —

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

  • :after (String) —

    The ID after which to retrieve more delivery attempts

Returns:

  • (Hash) —

    A paginated list of webhook event delivery attempts



156
157
158
159
160
 
# File 'lib/resend/webhooks.rb', line 156

def list_event_attempts(webhook_id, event_id, params = {})
  base_path = "webhooks/#{webhook_id}/events/#{event_id}/attempts"
  path = Resend::PaginationHelper.build_paginated_path(base_path, params)
  Resend::Request.new(path, {}, "get").perform
end

.list_events(webhook_id, params = {}) ⇒ Hash

Retrieve webhook events

Examples:

Resend::Webhooks.list_events("4dd369bc-aa82-4ff3-97de-514ae3000ee0")

With pagination

Resend::Webhooks.list_events("4dd369bc-aa82-4ff3-97de-514ae3000ee0", limit: 20, after: "msg_123")

Parameters:

  • webhook_id (String) —

    The webhook ID

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

    The pagination parameters

Options Hash (params):

  • :limit (Integer) —

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

  • :after (String) —

    The ID after which to retrieve more webhook events

Returns:

  • (Hash) —

    A paginated list of webhook events



101
102
103
104
 
# File 'lib/resend/webhooks.rb', line 101

def list_events(webhook_id, params = {})
  path = Resend::PaginationHelper.build_paginated_path("webhooks/#{webhook_id}/events", params)
  Resend::Request.new(path, {}, "get").perform
end

.remove(webhook_id = "") ⇒ Hash

Remove an existing webhook

Examples:

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

Parameters:

  • webhook_id (String) (defaults to: "") —

    The webhook ID

Returns:

  • (Hash) —

    Confirmation object with id, object type, and deleted status



208
209
210
211
 
# File 'lib/resend/webhooks.rb', line 208

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

.replay_event(webhook_id, event_id) ⇒ Hash

Replay a webhook event

Queues one more delivery of the event to the webhook. Manual replays do not schedule automatic retries.

Examples:

Resend::Webhooks.replay_event("4dd369bc-aa82-4ff3-97de-514ae3000ee0", "msg_123")

Parameters:

  • webhook_id (String) —

    The webhook ID

  • event_id (String) —

    The webhook event ID

Returns:

  • (Hash) —

    The replayed webhook event id and object type



131
132
133
134
 
# File 'lib/resend/webhooks.rb', line 131

def replay_event(webhook_id, event_id)
  path = "webhooks/#{webhook_id}/events/#{event_id}/replay"
  Resend::Request.new(path, {}, "post").perform
end

.rotate_signing_secret(webhook_id) ⇒ Hash

Rotate the signing secret of a webhook

Generates a new signing secret for the webhook. The previous secret keeps working for 24 hours.

Examples:

Resend::Webhooks.rotate_signing_secret("4dd369bc-aa82-4ff3-97de-514ae3000ee0")

Parameters:

  • webhook_id (String) —

    The webhook ID

Returns:

  • (Hash) —

    The webhook object containing id, object type, and the new signing_secret



195
196
197
198
 
# File 'lib/resend/webhooks.rb', line 195

def rotate_signing_secret(webhook_id)
  path = "webhooks/#{webhook_id}/signing-secret/rotate"
  Resend::Request.new(path, {}, "post").perform
end

.update(params = {}) ⇒ Hash

Update an existing webhook configuration

Examples:

Resend::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



179
180
181
182
183
 
# File 'lib/resend/webhooks.rb', line 179

def update(params = {})
  webhook_id = params.delete(:webhook_id)
  path = "webhooks/#{webhook_id}"
  Resend::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 Resend and hasn't been tampered with

Examples:

Resend::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



235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/resend/webhooks.rb', line 235

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