Class: Nfe::Resources::Webhooks

Inherits:
AbstractResource show all
Defined in:
lib/nfe/resources/webhooks.rb,
sig/nfe/resources/webhooks.rbs

Overview

Webhooks resource, company-scoped under /companies/{id}/webhooks on the :main host family. Exposes CRUD, a synthetic-delivery test, the static list of available events, and a thin #verify_signature delegation to Webhook (the canonical signature-verification API is the module).

Constant Summary collapse

AVAILABLE_EVENTS =

The seven event types the NFE.io API can deliver (parity with Node).

Returns:

  • (Array[String]) 
%w[
  invoice.issued
  invoice.cancelled
  invoice.failed
  invoice.processing
  company.created
  company.updated
  company.deleted
].freeze

Instance Attribute Summary

Attributes inherited from AbstractResource

#client

Instance Method Summary collapse

Methods inherited from AbstractResource

#api_version, #build_list_page, #build_multipart_body, #cursor_list_page, #dig_key, #download, #extract_invoice_id, #full_path, #get, #handle_async_response, #hydrate, #hydrate_list, #initialize, #multipart_part, #page_list_page, #parse_json, #post, #put, #unwrap, #upload_multipart

Constructor Details

This class inherits a constructor from Nfe::Resources::AbstractResource

Instance Method Details

#api_family ⇒ Symbol

Returns:

  • (Symbol) 


28
29
30
 
# File 'lib/nfe/resources/webhooks.rb', line 28

def api_family
  :main
end

#create(company_id, data) ⇒ Nfe::Webhook

Create a webhook subscription. Accepts url, events, secret, active.

Parameters:

  • company_id (String)
  • data (Hash)

Returns:



51
52
53
54
55
56
 
# File 'lib/nfe/resources/webhooks.rb', line 51

def create(company_id, data)
  id = Nfe::IdValidator.company_id(company_id)
  response = post("/companies/#{id}/webhooks",
                  body: json_body(data), headers: json_headers)
  hydrate(Nfe::WebhookSubscription, parse_json(response.body))
end

#delete(company_id, webhook_id) ⇒ nil

Delete a webhook.

Parameters:

  • company_id (String)
  • webhook_id (String)

Returns:

  • (nil) 


89
90
91
92
93
94
 
# File 'lib/nfe/resources/webhooks.rb', line 89

def delete(company_id, webhook_id)
  id = Nfe::IdValidator.company_id(company_id)
  wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
  super("/companies/#{id}/webhooks/#{wid}")
  nil
end

#get_available_events ⇒ Array<String>

The static list of webhook event types the API can deliver.

Returns:

  • (Array<String>) 


113
114
115
 
# File 'lib/nfe/resources/webhooks.rb', line 113

def get_available_events
  AVAILABLE_EVENTS.dup
end

#json_body(data) ⇒ String

Parameters:

  • data (Object)

Returns:

  • (String) 


131
132
133
 
# File 'lib/nfe/resources/webhooks.rb', line 131

def json_body(data)
  JSON.generate(data)
end

#json_headers ⇒ Hash[String, String]

Returns:

  • (Hash[String, String]) 


127
128
129
 
# File 'lib/nfe/resources/webhooks.rb', line 127

def json_headers
  { "Content-Type" => "application/json" }
end

#list(company_id) ⇒ Nfe::ListResponse

List a company's webhook subscriptions.

Parameters:

  • company_id (String)

Returns:



38
39
40
41
42
43
44
 
# File 'lib/nfe/resources/webhooks.rb', line 38

def list(company_id)
  id = Nfe::IdValidator.company_id(company_id)
  response = get("/companies/#{id}/webhooks")
  payload = parse_json(response.body)
  items = webhook_items(payload).map { |item| hydrate(Nfe::WebhookSubscription, item) }
  Nfe::ListResponse.new(data: items)
end

#retrieve(company_id, webhook_id) ⇒ Nfe::Webhook

Retrieve a webhook by id.

Parameters:

  • company_id (String)
  • webhook_id (String)

Returns:



63
64
65
66
67
68
 
# File 'lib/nfe/resources/webhooks.rb', line 63

def retrieve(company_id, webhook_id)
  id = Nfe::IdValidator.company_id(company_id)
  wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
  response = get("/companies/#{id}/webhooks/#{wid}")
  hydrate(Nfe::WebhookSubscription, parse_json(response.body))
end

#test(company_id, webhook_id) ⇒ Hash

Trigger a synthetic delivery to verify a webhook is reachable.

Parameters:

  • company_id (String)
  • webhook_id (String)

Returns:

  • (Hash) —

    { success: bool, message: String? }.



101
102
103
104
105
106
107
108
 
# File 'lib/nfe/resources/webhooks.rb', line 101

def test(company_id, webhook_id)
  id = Nfe::IdValidator.company_id(company_id)
  wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
  response = post("/companies/#{id}/webhooks/#{wid}/test",
                  body: json_body({}), headers: json_headers)
  payload = parse_json(response.body) || {}
  { success: payload["success"] || false, message: payload["message"] }
end

#update(company_id, webhook_id, data) ⇒ Nfe::Webhook

Update a webhook.

Parameters:

  • company_id (String)
  • webhook_id (String)
  • data (Hash)

Returns:



76
77
78
79
80
81
82
 
# File 'lib/nfe/resources/webhooks.rb', line 76

def update(company_id, webhook_id, data)
  id = Nfe::IdValidator.company_id(company_id)
  wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
  response = put("/companies/#{id}/webhooks/#{wid}",
                 body: json_body(data), headers: json_headers)
  hydrate(Nfe::WebhookSubscription, parse_json(response.body))
end

#verify_signature(payload:, signature:, secret:) ⇒ Boolean

Verify a webhook signature. Thin delegation to Webhook for Node parity; the canonical API is the module. Never raises.

Parameters:

  • payload: (String)
  • signature: (String, Array[String], nil)
  • secret: (String, nil)

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/nfe/resources/webhooks.rb', line 121

def verify_signature(payload:, signature:, secret:)
  Nfe::Webhook.verify_signature(payload: payload, signature: signature, secret: secret)
end

#webhook_items(payload) ⇒ Array[untyped]

Tolerate either a bare array, a +data+-wrapped list, or a webhooks envelope for the list response.

Parameters:

  • payload (Object)

Returns:

  • (Array[untyped]) 


137
138
139
140
141
142
 
# File 'lib/nfe/resources/webhooks.rb', line 137

def webhook_items(payload)
  return payload if payload.is_a?(Array)
  return [] unless payload.is_a?(Hash)

  payload["data"] || payload["webhooks"] || payload[:data] || payload[:webhooks] || []
end