Class: RelayGrid::Resources::WebhookEndpoints

Inherits:
Object
  • Object
show all
Defined in:
lib/relaygrid/resources/webhook_endpoints.rb

Overview

Manage the HTTPS endpoint RelayGrid pushes delivery-status events to.

Registering one is what replaces polling: instead of calling wait_for_deliveries, your app receives delivery.* events as they happen and verifies them with RelayGrid::Webhooks.construct_event.

endpoint = client.webhook_endpoints.create(url: "https://app.example.com/relaygrid/webhooks")
endpoint["secret"] # => "whsec_..." -- returned here and on rotate only

Store that secret before you drop the response: list and show return only a preview of it.

An account has one endpoint. list is still a collection for forward compatibility, but it holds at most one entry, and creating a second is a 409 -- change the URL with #update, or #delete and re-create.

Constant Summary collapse

PATH = 
"/api/v1/webhook_endpoints"

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ WebhookEndpoints

Returns a new instance of WebhookEndpoints.



23
24
25
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 23

def initialize(client)
  @client = client
end

Instance Method Details

#attempts(id) ⇒ Array<Hash>

Recent dispatch attempts, newest first: response codes, errors and durations. The "why didn't my webhook arrive?" log.

Returns:

  • (Array<Hash>) 


103
104
105
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 103

def attempts(id)
  Array(@client.get("#{PATH}/#{id}/attempts")["attempts"])
end

#create(url:) ⇒ Hash

An endpoint receives every event type, including ones added later, so there is nothing to subscribe to -- switch on event.type in your receiver instead.

Parameters:

  • url (String) —

    an https URL on a publicly resolvable host

Returns:

  • (Hash) —

    including the plaintext "secret"

Raises:



56
57
58
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 56

def create(url:)
  @client.post(PATH, body: { webhook_endpoint: { url: url } })["webhook_endpoint"]
end

#current ⇒ Hash?

The account's endpoint, or nil when none is registered.

Returns:

  • (Hash, nil) 


35
36
37
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 35

def current
  list.first
end

#delete(id) ⇒ true

Returns:

  • (true) 


70
71
72
73
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 70

def delete(id)
  @client.delete("#{PATH}/#{id}")
  true
end

#get(id) ⇒ Hash

Parameters:

  • id (Integer)

Returns:

  • (Hash)

Raises:



42
43
44
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 42

def get(id)
  @client.get("#{PATH}/#{id}")["webhook_endpoint"]
end

#list ⇒ Array<Hash>

Returns at most one entry.

Returns:

  • (Array<Hash>) —

    at most one entry



28
29
30
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 28

def list
  Array(@client.get(PATH)["webhook_endpoints"])
end

#reactivate(id) ⇒ Hash

Clear the auto-disabled state after fixing a receiver RelayGrid gave up on.

Returns:

  • (Hash) 


86
87
88
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 86

def reactivate(id)
  @client.post("#{PATH}/#{id}/reactivate")["webhook_endpoint"]
end

#rotate_secret(id) ⇒ Hash

Issue a new signing secret, returned in full. The previous secret stops working at once, so deploy the new one to your receiver first.

Returns:

  • (Hash) —

    including the plaintext "secret"



79
80
81
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 79

def rotate_secret(id)
  @client.post("#{PATH}/#{id}/rotate_secret")["webhook_endpoint"]
end

#test(id) ⇒ String

Queue a signed ping so you can confirm the URL and secret work before real traffic depends on them. Delivery is asynchronous -- check #attempts for the result.

Returns:

  • (String) —

    the event id that was queued



95
96
97
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 95

def test(id)
  @client.post("#{PATH}/#{id}/test")["event_id"]
end

#update(id, url: nil, active: nil) ⇒ Hash

Returns:

  • (Hash) 


61
62
63
64
65
66
67
 
# File 'lib/relaygrid/resources/webhook_endpoints.rb', line 61

def update(id, url: nil, active: nil)
  attributes = {}
  attributes[:url] = url unless url.nil?
  attributes[:active] = active unless active.nil?

  @client.patch("#{PATH}/#{id}", body: { webhook_endpoint: attributes })["webhook_endpoint"]
end