Class: Asana::Resources::Webhook
- Defined in:
- lib/asana/resources/webhook.rb
Overview
Webhooks allow an application to be notified of changes. This is in addition to the ability to fetch those changes directly as [Events](/developers/api-reference/events) - in fact, Webhooks are just a way to receive Events via HTTP POST at the time they occur instead of polling for them. For services accessible via HTTP this is often vastly more convenient, and if events are not too frequent can be significantly more efficient.
In both cases, however, changes are represented as Event objects - refer to the [Events documentation](/developers/api-reference/events) for more information on what data these events contain.
NOTE: While Webhooks send arrays of Event objects to their target, the Event objects themselves contain *only IDs*, rather than the actual resource they are referencing. So while a normal event you receive via GET /events would look like this:
{\
"resource": {\
"id": 1337,\
"name": "My Task"\
},\
"parent": null,\
"created_at": "2013-08-21T18:20:37.972Z",\
"user": {\
"id": 1123,\
"name": "Tom Bizarro"\
},\
"action": "changed",\
"type": "task"\
}
In a Webhook payload you would instead receive this:
{\
"resource": 1337,\
"parent": null,\
"created_at": "2013-08-21T18:20:37.972Z",\
"user": 1123,\
"action": "changed",\
"type": "task"\
}
Webhooks themselves contain only the information necessary to deliver the events to the desired target as they are generated.
Instance Attribute Summary collapse
- #active ⇒ Object readonly
- #created_at ⇒ Object readonly
- #id ⇒ Object readonly
- #last_failure_at ⇒ Object readonly
- #last_failure_content ⇒ Object readonly
- #last_success_at ⇒ Object readonly
- #resource ⇒ Object readonly
- #target ⇒ Object readonly
Class Method Summary collapse
-
.create(client, resource: required("resource"), target: required("target"), options: {}, **data) ⇒ Object
Establishing a webhook is a two-part process.
-
.get_all(client, workspace: required("workspace"), resource: nil, per_page: 20, options: {}) ⇒ Object
Returns the compact representation of all webhooks your app has registered for the authenticated user in the given workspace.
-
.get_by_id(client, id, options: {}) ⇒ Object
Returns the full record for the given webhook.
-
.plural_name ⇒ Object
Returns the plural name of the resource.
Instance Method Summary collapse
-
#delete_by_id ⇒ Object
This method permanently removes a webhook.
Methods inherited from Resource
inherited, #initialize, #method_missing, #refresh, #respond_to_missing?, #to_h, #to_s
Methods included from ResponseHelper
Constructor Details
This class inherits a constructor from Asana::Resources::Resource
Dynamic Method Handling
This class handles dynamic methods through the method_missing method in the class Asana::Resources::Resource
Instance Attribute Details
#active ⇒ Object (readonly)
59 60 61 |
# File 'lib/asana/resources/webhook.rb', line 59 def active @active end |
#created_at ⇒ Object (readonly)
61 62 63 |
# File 'lib/asana/resources/webhook.rb', line 61 def created_at @created_at end |
#id ⇒ Object (readonly)
53 54 55 |
# File 'lib/asana/resources/webhook.rb', line 53 def id @id end |
#last_failure_at ⇒ Object (readonly)
65 66 67 |
# File 'lib/asana/resources/webhook.rb', line 65 def last_failure_at @last_failure_at end |
#last_failure_content ⇒ Object (readonly)
67 68 69 |
# File 'lib/asana/resources/webhook.rb', line 67 def last_failure_content @last_failure_content end |
#last_success_at ⇒ Object (readonly)
63 64 65 |
# File 'lib/asana/resources/webhook.rb', line 63 def last_success_at @last_success_at end |
#resource ⇒ Object (readonly)
55 56 57 |
# File 'lib/asana/resources/webhook.rb', line 55 def resource @resource end |
#target ⇒ Object (readonly)
57 58 59 |
# File 'lib/asana/resources/webhook.rb', line 57 def target @target end |
Class Method Details
.create(client, resource: required("resource"), target: required("target"), options: {}, **data) ⇒ Object
Establishing a webhook is a two-part process. First, a simple HTTP POST similar to any other resource creation. Since you could have multiple webhooks we recommend specifying a unique local id for each target.
Next comes the confirmation handshake. When a webhook is created, we will send a test POST to the ‘target` with an `X-Hook-Secret` header as described in the [Resthooks Security documentation](resthooks.org/docs/security/). The target must respond with a `200 OK` and a matching `X-Hook-Secret` header to confirm that this webhook subscription is indeed expected.
If you do not acknowledge the webhook’s confirmation handshake it will fail to setup, and you will receive an error in response to your attempt to create it. This means you need to be able to receive and complete the webhook while the POST request is in-flight.
97 98 99 100 |
# File 'lib/asana/resources/webhook.rb', line 97 def create(client, resource: required("resource"), target: required("target"), options: {}, **data) with_params = data.merge(resource: resource, target: target).reject { |_,v| v.nil? || Array(v).empty? } self.new(parse(client.post("/webhooks", body: with_params, options: )).first, client: client) end |
.get_all(client, workspace: required("workspace"), resource: nil, per_page: 20, options: {}) ⇒ Object
Returns the compact representation of all webhooks your app has registered for the authenticated user in the given workspace.
111 112 113 114 |
# File 'lib/asana/resources/webhook.rb', line 111 def get_all(client, workspace: required("workspace"), resource: nil, per_page: 20, options: {}) params = { workspace: workspace, resource: resource, limit: per_page }.reject { |_,v| v.nil? || Array(v).empty? } Collection.new(parse(client.get("/webhooks", params: params, options: )), type: self, client: client) end |
.get_by_id(client, id, options: {}) ⇒ Object
Returns the full record for the given webhook.
121 122 123 124 |
# File 'lib/asana/resources/webhook.rb', line 121 def get_by_id(client, id, options: {}) self.new(parse(client.get("/webhooks/#{id}", options: )).first, client: client) end |
.plural_name ⇒ Object
Returns the plural name of the resource.
71 72 73 |
# File 'lib/asana/resources/webhook.rb', line 71 def plural_name 'webhooks' end |
Instance Method Details
#delete_by_id ⇒ Object
This method permanently removes a webhook. Note that it may be possible to receive a request that was already in flight after deleting the webhook, but no further requests will be issued.
130 131 132 133 |
# File 'lib/asana/resources/webhook.rb', line 130 def delete_by_id() self.class.new(parse(client.delete("/webhooks/#{id}")).first, client: client) end |