Class: Asana::Resources::Webhook

Inherits:
Resource
  • Object
show all
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,\
    "resource_type": "task",\
    "name": "My Task"\
  },\
  "parent": null,\
  "created_at": "2013-08-21T18:20:37.972Z",\
  "user": {\
    "id": 1123,\
    "resource_type": "user",\
    "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

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Resource

inherited, #initialize, #method_missing, #refresh, #respond_to_missing?, #to_h, #to_s

Methods included from ResponseHelper

#parse

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) 



65
66
67
 
# File 'lib/asana/resources/webhook.rb', line 65

def active
  @active
end

#created_at ⇒ Object (readonly) 



67
68
69
 
# File 'lib/asana/resources/webhook.rb', line 67

def created_at
  @created_at
end

#gid ⇒ Object (readonly) 



57
58
59
 
# File 'lib/asana/resources/webhook.rb', line 57

def gid
  @gid
end

#id ⇒ Object (readonly) 



55
56
57
 
# File 'lib/asana/resources/webhook.rb', line 55

def id
  @id
end

#last_failure_at ⇒ Object (readonly) 



71
72
73
 
# File 'lib/asana/resources/webhook.rb', line 71

def last_failure_at
  @last_failure_at
end

#last_failure_content ⇒ Object (readonly) 



73
74
75
 
# File 'lib/asana/resources/webhook.rb', line 73

def last_failure_content
  @last_failure_content
end

#last_success_at ⇒ Object (readonly) 



69
70
71
 
# File 'lib/asana/resources/webhook.rb', line 69

def last_success_at
  @last_success_at
end

#resource ⇒ Object (readonly) 



61
62
63
 
# File 'lib/asana/resources/webhook.rb', line 61

def resource
  @resource
end

#resource_type ⇒ Object (readonly) 



59
60
61
 
# File 'lib/asana/resources/webhook.rb', line 59

def resource_type
  @resource_type
end

#target ⇒ Object (readonly) 



63
64
65
 
# File 'lib/asana/resources/webhook.rb', line 63

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.

Parameters:

  • resource (Id) (defaults to: required("resource")) —

    A resource ID to subscribe to. The resource can be a task or project.

  • target (String) (defaults to: required("target")) —

    The URL to receive the HTTP POST.

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

    the request I/O options.

  • data (Hash) —

    the attributes to post.



103
104
105
106
 
# File 'lib/asana/resources/webhook.rb', line 103

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

Parameters:

  • workspace (Id) (defaults to: required("workspace")) —

    The workspace to query for webhooks in.

  • resource (Id) (defaults to: nil) —

    Only return webhooks for the given resource.

  • per_page (Integer) (defaults to: 20) —

    the number of records to fetch per page.

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

    the request I/O options.



117
118
119
120
 
# File 'lib/asana/resources/webhook.rb', line 117

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: options)), type: self, client: client)
end

.get_by_id(client, id, options: {}) ⇒ Object

Returns the full record for the given webhook.

Parameters:

  • id (Id) —

    The webhook to get.

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

    the request I/O options.



127
128
129
130
 
# File 'lib/asana/resources/webhook.rb', line 127

def get_by_id(client, id, options: {})

  self.new(parse(client.get("/webhooks/#{id}", options: options)).first, client: client)
end

.plural_name ⇒ Object

Returns the plural name of the resource.



77
78
79
 
# File 'lib/asana/resources/webhook.rb', line 77

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.



136
137
138
139
 
# File 'lib/asana/resources/webhook.rb', line 136

def delete_by_id()

  self.class.new(parse(client.delete("/webhooks/#{gid}")).first, client: client)
end