WoodWing Help Center

Elvis 6 REST API - Managing Webhooks

Elvis 6 REST API - Managing Webhooks

This article describes the various methods of using the Webhooks API.

For more information, see Working with Webhooks in Elvis 6.

Registering a new Webhook

POST

http://yourserver.com/services/admin/webhook

What does it do?

Create a new Webhook.

Path Variables

None.

Parameters

None.

Request body

To register the Webhook, a JSON body containing the following fields is required:

Name Type Description
name String Name of the Webhook.
url String URL containing the location of the Webhook.
eventTypes String array A list containing one or more types of events that should be posted to the Webhook. This list may be empty, but not null.
metadataToReturn String array Optional. List of metadata fields which are returned for every event.

Return value

If successful, a JSON object containing the following fields will be returned:

Name Type Description
name String Name of the Webhook.
id String Elvis-generated ID for the Webhook.
url String Location of the Webhook.
eventTypes String array List of types of events the Webhook receives.
metadataToReturn String array List of metadata fields which are returned for every event.
enabled boolean (Default: true) Boolean stating whether the Webhook is enabled.
secretToken String Randomly generated AES key that is used for verifying the origin of Webhook calls.

Examples

Successful call

  • Create new Webhook
POST http://yourserver.com/services/admin/webhook
Content: {
		   "name" : "My Webhook",
		   "url" : "http://locationofa.webhook.com/some/path",
                   "eventTypes" : ["asset_rename", "asset_update_metadata"]
                }

Returns the following response:

Status Code: 201 Created
Content: {
                   "id": "C__FNux9av_BIfk3VDyuO8",
                   "name" : "My Webhook",
                   "url": "http://locationofa.webhook.com/some/path",
                   "eventTypes": [
                                   "asset_update_metadata",
                                   "asset_rename"
                   ],
                   "enabled": true,
                   "secretToken": "WMh2H3+53FHkQMNpRMwetw=="
                }

Erroneous calls

  • Supplying an invalid URL
POST http://yourserver.com/services/admin/webhook
Content: {
		   "name" : "My Webhook",
		   "url" : "bogus_url",
                   "eventTypes" : ["asset_rename", "asset_update_metadata"]
                }

Returns the following error:

Status code: 200 OK
Content: {
                   "errorname": "MethodArgumentNotValidException",
                   "message": "Must be a valid URL",
                   "errorcode": 500
                 }
  • Not supplying a field (eventTypes in this case)
POST http://yourserver.com/services/admin/webhook
Content: {
		    "name" : "My Webhook",
		    "url" : "http://locationofa.webhook.com/some/path"
                }

Returns the following error:

Status code: 200 OK
Content: {
                   "errorname": "MethodArgumentNotValidException",
                   "message": "May not be null",
                   "errorcode": 500
		}

Updating a Webhook

PUT

http://yourserver.com/services/admin/webhook/:id

What does it do?

Update the fields of a Webhook.

Path variables

None.

Request body

Provide the fields of the Webhook that need to be updated.

Name Type Description
name String Optional: New name for the Webhook.
url String Optional: New URL for the Webhook.
eventTypes Set<String> Optional: New event types for the Webhook.
metadataToReturn Set<String> Optional: New metadata to return.
enabled boolean Optional: Set Webhook enabled or disabled.

Note: Fields that are left null will not be updated.

Return value

If successful, the updated Webhook object will be returned, containing the following fields:

Name Type Description
name String Name of the Webhook.
id String ID of the Webhook.
url String Location of the Webhook.
eventTypes String array List of types of events the Webhook receives.
metadataToReturn String array List of metadata fields which are returned for every event.
enabled boolean Boolean stating whether the Webhook is enabled.
secretToken String Randomly generated AES key that is used for verifying the origin of Webhook calls.

Examples

Successful calls

  • Update URL and Event Types of a Webhook
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8

Content: {   
                   "url" : "http://locationofa.webhook.com/some/new/path",
                   "eventTypes" : ["asset_create"]
                }

Returns the following response:

Status Code: 200 OK
Content: {
		   "id": "C__FNux9av_BIfk3VDyuO8",
		   "name": "My Webhook",
                   "url": "http://locationofa.webhook.com/some/new/path",
                   "eventTypes": [
                       "asset_create"
                   ],
                   "metadataToReturn": [
                                   "status"
                   ],
                   "enabled": true,
                   "secretToken": "WMh2H3+53FHkQMNpRMwetw=="
                }
  • Disabling a Webhook
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8
Content: {
                   "enabled": false,
                }

Returns the following response:

Status Code: 200 OK
Content: {
		   "id": "C__FNux9av_BIfk3VDyuO8",
		   "name": "My Webhook",
                   "url": "http://locationofa.webhook.com/some/path",
                   "eventTypes": [
                       "asset_checkin",
                       "asset_checkout",
                       "asset_undo_checkout"
                   ],
                   "metadataToReturn": [
                       "status"
                   ],

                   "enabled": false,
                   "secretToken": "WMh2H3+53FHkQMNpRMwetw=="
                }

Erroneous calls

  • Invalid event types
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8

Content: {   
                   "eventTypes" : ["bogus_event"]
                }

Returns the following response:

Status code: 200 OK
Content: {
                   "errorname": "MethodArgumentNotValidException",
                   "message": "Invalid Event Types found.",
                   "errorcode": 400
                }
  • Webhook with provided ID does not exist.
PUT http://yourserver.com/services/admin/webhook/bogus_id

Returns the following response:

Status code: 404 Not Found
Content: "Webhook not found."

Generating a new secret token for a Webhook

PUT

http://yourserver.com/services/admin/webhook/:id/generate-token

What does it do?

Generate a new secret token for a Webhook.

Path variables

id ID of the Webhook to generate a new secret token for.

Parameters

None.

Return value

A String containing the new secret token.

Examples

Successful call

  • Update Event Types of a Webhook
PUT http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8/generate-token

Returns the following response:

Status Code: 200 OK
Content: {
                   "secretToken"  : "WMh2H3+53FHkQMNpRMwetw=="
                }
  • Webhook with provided ID does not exist.
PUT http://yourserver.com/services/admin/webhook/bogus_id/generate-token

Returns the following response:

Status code: 404 Not Found
Content: "Webhook not found."

Deleting a Webhook

DELETE

http://yourserver.com/services/admin/webhook/:id

What does it do?

Delete a Webhook.

Path variables

id ID of the Webhook to delete.

Note: For testing purposes, you can provide “all” instead of the ID to quickly delete all registered Webhooks.

Parameters

None.

Return value

Returns a 204 No Content message when the Webhook has been successfully deleted or a 404 Not Found error when a non-existing or invalid ID was supplied.

Examples

Successful call

  • Delete a Webhook
DELETE http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8

Returns the following response:

Status code: 204 No Content

Erroneous call

  • Webhook with provided ID does not exist.
GET http://yourserver.com/services/admin/webhook/bogus_id

Returns the following response:

Status code: 404 Not Found
Content: "Webhook not found."

Querying all Webhooks

GET

http://yourserver.com/services/admin/webhook

What does it do?

Returns a list of all registered Webhooks.

Parameters

None.

Return value

A JSON object containing a list of Webhook objects or an empty list when no Webhooks exist.

A single Webhook object contains the following data:

Name Type Description
name String Name of the Webhook.
id String ID of the Webhook.
url String Location of the Webhook.
eventTypes String array List of types of events the Webhook receives.
enabled boolean Boolean stating whether the Webhook is enabled. Disabled Webhooks do not receive updates.
secretToken String Randomly generated AES key that is used for verifying the origin of Webhook calls.

Examples

Successful call

  • Show all Webhooks
GET http://yourserver.com/services/admin/webhook

Returns the following response:

Status code: 200 OK
Content: [ 
      {
id: "C__FNux9av_BIfk3VDyuO8",
"name" : "My Webhook",
url: "http://locationofa.webhook.com/some/path",
eventTypes: 
[
"asset_update_metadata",
"asset_rename"
],
enabled: true,
secretToken: "kwQMEL5dGdyey7Cdzo4PYQ=="
         },
         {
id: "0ldCt5DBKpw94GG3EcTT_N",
"name" : "My other Webhook",
url: "http://locationofa.webhook.com/some/other/path",
eventTypes: 
[
"asset_checkout",
"asset_checkin",
"asset_undo_checkout"
],
enabled: false,
secretToken: "WMh2H3+53FHkQMNpRMwetw=="
          }
                 ]

Erroneous call

  • Not logged in
GET http://yourserver.com/services/admin/webhook

Returns the following response:

Status code: 200 OK
Content: {
                   "errorname": "UNAUTHORIZED",
                   "message": "Not logged in",
                   "errorcode": 401
                 }

Querying Webhooks by ID

GET

http://yourserver.com/services/admin/webhook/:id

What does it do?

Returns a single Webhook.

Path variables

id ID of the Webhook to return.

Parameters

None.

Return value

A JSON object containing the Webhook. If a Webhook with the provided ID does not exist, a “Not Found” response containing “Webhook not found.” will be returned.

A Webhook object contains the following data:

Name Type Description
name String Name of the Webhook.
id String ID of the Webhook.
url String Location of the Webhook.
eventTypes String array List of types of events the Webhook receives.
metadataToReturn String array List of metadata fields which are returned for every event.
enabled boolean Boolean stating whether the Webhook is enabled.
secretToken String Randomly generated AES key that is used for verifying the origin of Webhook calls.

Examples

Successful call

  • Show gingle Webhook
GET http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8

Returns the following response:

Status code: 200 OK
Content: {
	   id: "C__FNux9av_BIfk3VDyuO8",
	   "name": "My Webhook",
            url: "http://locationofa.webhook.com/some/path",
            eventTypes: 
            [
       "asset_update_metadata",
       "asset_rename"
            ],
            enabled: true,
            secretToken: "kwQMEL5dGdyey7Cdzo4PYQ=="
     }

Erroneous calls

  • Webhook with provided ID does not exist.
GET http://yourserver.com/services/admin/webhook/bogus_id

Returns the following response:

Status code: 404 Not Found Content: "Webhook not found."

  • Not logged in

GET http://yourserver.com/services/admin/webhook/C__FNux9av_BIfk3VDyuO8

Returns the following response:

Status code: 200 OK
Content: {
                   "errorname": "UNAUTHORIZED",
                   "message": "Not logged in",
                   "errorcode": 401
                 }
Was this article helpful?
0 out of 0 found this helpful / Created: / Updated:
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.