Module: JetEmail::Webhooks

Defined in:
lib/jetemail/webhooks.rb

Class Method Summary collapse

Class Method Details

.create(params) ⇒ Hash

Create a webhook.

Parameters:

  • params (Hash) —

    Webhook parameters

Options Hash (params):

  • :name (String) —

    Required. Webhook name

  • :url (String) —

    Required. Webhook URL

  • :events (Array<String>) —

    Required. Event types to subscribe to

Returns:

  • (Hash) —

    Created webhook



34
35
36
37
 
# File 'lib/jetemail/webhooks.rb', line 34

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

.get(uuid) ⇒ Hash

Get a single webhook.

Parameters:

  • uuid (String) —

    Webhook UUID

Returns:

  • (Hash) —

    Webhook details



22
23
24
25
 
# File 'lib/jetemail/webhooks.rb', line 22

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

.list ⇒ Hash

List all webhooks.

Returns:

  • (Hash) —

    List of webhooks



13
14
15
16
 
# File 'lib/jetemail/webhooks.rb', line 13

def list
  path = "webhooks"
  JetEmail::Request.new(path, {}, "get").perform
end

.query(params = {}) ⇒ Hash

Query webhook events.

Parameters:

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

    Query filters

Returns:

  • (Hash) —

    Matching webhook events



62
63
64
65
 
# File 'lib/jetemail/webhooks.rb', line 62

def query(params = {})
  path = "webhooks/query"
  JetEmail::Request.new(path, params, "post").perform
end

.remove(uuid) ⇒ Hash

Delete a webhook.

Parameters:

  • uuid (String) —

    Webhook UUID

Returns:

  • (Hash) —

    Deletion confirmation



53
54
55
56
 
# File 'lib/jetemail/webhooks.rb', line 53

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

.replay(params) ⇒ Hash

Replay a webhook event.

Parameters:

  • params (Hash) —

    Replay parameters

Options Hash (params):

  • :event_id (String) —

    Event ID to replay

  • :source_uid (String) —

    Source UID to replay

Returns:

  • (Hash) —

    Replay confirmation



73
74
75
76
 
# File 'lib/jetemail/webhooks.rb', line 73

def replay(params)
  path = "webhooks/replay"
  JetEmail::Request.new(path, params, "post").perform
end

.update(params) ⇒ Hash

Update a webhook.

Parameters:

  • params (Hash) —

    Webhook parameters

Options Hash (params):

  • :uuid (String) —

    Required. Webhook UUID

Returns:

  • (Hash) —

    Updated webhook



44
45
46
47
 
# File 'lib/jetemail/webhooks.rb', line 44

def update(params)
  path = "webhooks"
  JetEmail::Request.new(path, params, "patch").perform
end

.verify(payload:, signature:, timestamp:, secret:, tolerance: WEBHOOK_TOLERANCE_SECONDS) ⇒ Boolean

Verify a webhook signature.

Parameters:

  • payload (String) —

    Raw request body

  • signature (String) —

    X-Webhook-Signature header value

  • timestamp (String) —

    X-Webhook-Timestamp header value

  • secret (String) —

    Your webhook secret

  • tolerance (Integer) (defaults to: WEBHOOK_TOLERANCE_SECONDS) —

    Max age in seconds (default: 300)

Returns:

  • (Boolean) —

    true if valid

Raises:



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/jetemail/webhooks.rb', line 87

def verify(payload:, signature:, timestamp:, secret:, tolerance: WEBHOOK_TOLERANCE_SECONDS)
  raise JetEmail::Error.new("Payload cannot be empty") if payload.nil? || payload.empty?
  raise JetEmail::Error.new("Signature cannot be empty") if signature.nil? || signature.empty?
  raise JetEmail::Error.new("Timestamp cannot be empty") if timestamp.nil? || timestamp.to_s.empty?
  raise JetEmail::Error.new("Secret cannot be empty") if secret.nil? || secret.empty?

  ts = timestamp.to_i
  diff = (Time.now.to_i - ts).abs
  if tolerance > 0 && diff > tolerance
    raise JetEmail::Error.new("Webhook timestamp is outside tolerance (#{diff}s)")
  end

  expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
  unless secure_compare(expected, signature)
    raise JetEmail::Error.new("Webhook signature verification failed")
  end

  true
end