REST Hooks and Event Notifications

REST Hooks is a simple and easy-to-use mechanism for your application to receive notifications when specific events are triggered within Actionstep. To receive an event notification you have to register a callback url against a specific Actionstep event.

Supported Events

Event	Description
ActionCreated	Raised when a new action (matter) is created.
ActionUpdated	Raised when an existing action (matter) is updated.
ActionDocumentCreated	Raised when a new action (matter) document is created.
ActionDocumentUpdated	Raised when an existing action (matter) document is updated.
ActionDocumentDeleted	Raised when an existing action (matter) document is deleted.
ActionParticipantAdded	Raised when a new action (matter) participant is created.
ActionParticipantDeleted	Raised when an existing action (matter) participant is removed.
DataCollectionRecordUpdated	Raised when an individual custom data collection record is updated.
DataCollectionRecordDeleted	Raised when an individual custom data collection record is deleted.
DataCollectionRecordValueUpdated	Raised when an existing datacollection record value is updated.
DisbursementCreated	Raised when disbursement is created.
DisbursementUpdated	Raised when an existing disbursement is updated.
FileNoteCreated	Raised when a new file note is created.
FileNoteUpdated	Raised when a file note is updated.
ParticipantCreated	Raised when a new participant is created.
ParticipantUpdated	Raised when an existing participant is updated.
StepChanged	Raised when a step is changed in a workflow.
TaskCreated	Raised when a new task is created.
TaskUpdated	Raised when a task is updated.
TimeEntryCreated	Raised when time entry is created.
TimeEntryUpdated	Raised when an existing time entry is updated.

Registering a REST Hook

To register a REST Hook for one of the supported events use the resthooks API endpoint:

POST /api/rest/resthooks

{
	"resthooks": {
		"eventName": "ActionCreated",
		"targetUrl": "https://www.mydomain.com/path/endpoint"
	}
}

The response will be confirmation the REST Hook has been successfully registered (the same as a GET request).

{ 
    "resthooks": 
    { 
        "id": "382", 
        "eventName": "ActionCreated", 
        "targetUrl": "https://www.mydomain.com/path/endpoint", 
        "status": "Active", 
        "triggeredCount": 0,
        "lastTriggered": ""
    } 
}

NB: You can register multiple REST hooks for a single event if required.

Updating a REST Hook

To update an existing registered REST hook, for example, to change the callback url, make a PUT request. The response will be confirmation the REST hook has been successfully updated (the same as a GET request).

PUT /api/rest/resthooks/382

{
	"resthooks": {
		"eventName": "ActionCreated",
		"targetUrl": "https://www.mydomain.com/newpath/newendpoint"
	}
}

Deleting a REST Hook

To delete an existing REST hook make a DELETE request. The response will be confirmation the REST hook has been successfully deleted (the same as a GET request).

DELETE /api/rest/resthooks/382

Retrieving REST Hooks

You can retrieve the list of currently registered REST hooks, or the details of a single REST hook, by making a GET request.

GET /api/rest/resthooks

{ 
    "resthooks": 
    [
        { 
            "id": "382", 
            "eventName": "ActionCreated", 
            "targetUrl": "https://www.mydomain.com/path/endpoint", 
            "status": "Active", 
            "triggeredCount": 73,
            "lastTriggered": "2020-04-03T12:34:30+13:00"
        },
        { 
            "id": "746", 
            "eventName": "FileNoteCreated", 
            "targetUrl": "https://www.mydomain.com/anotherpath/anotherendpoint", 
            "status": "Disabled", 
            "triggeredCount": 28,
            "lastTriggered": "2020-05-20T09:29:52+13:00"
        },
    ] 
}

GET /api/rest/resthooks/382

{ 
    "resthooks": 
    { 
        "id": "382", 
        "eventName": "ActionCreated", 
        "targetUrl": "https://www.mydomain.com/path/endpoint", 
        "status": "Active", 
        "triggeredCount": 73,
        "lastTriggered": "2020-04-03T12:34:30+13:00"
    } 
}

Calling Target URLs

When an event is triggered, Actionstep will call the REST hook's target url. Actionstep deploys automatic retry logic to handle transient network errors that may arise from time to time. If Actionstep detects an unexpected error when calling your target url the REST hook will be disabled and the status set to "Disabled". Your target url must return an http status code of 200 to remain active.