Webhooks

The MASV API allows authorized users to connect their account to external web services to receive notification of activities within MASV via custom webhooks. They can be configured to receive a JSON formatted payload for a selection of events and are attached directly to MASV Portal(s). Events are emitted from MASV to each configured endpoint and are attempted up to 5 times.

Create webhook

Authorized users can create custom webhooks for any Team they belong to, subject to the access policy.

Method	Route
`POST`	`/teams/{team_id}/custom_webhooks`

Headers

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key
`Content-Type`	String	Yes	Must be `application/json`

Body

Name	Type	Required	Description
`active`	Boolean	Yes	Indicates if the webhook is active or not
`body_extras`	Object	No	A static list of keys and values to be appended to the body of all events. All values must be strings.
`events`	String[]	Yes	Indicates which events this webhook will receive (see supported events below)
`headers`	Object	No	A static list of header keys and values to be included on every event that is sent
`method`	String	Yes	Verb used when event is sent — `POST` and `PUT` are currently supported
`name`	String	No	Optional internal reference to the webhook and its purpose
`url`	String	Yes	The HTTP or HTTPS endpoint for events to be sent to

Request

curl -d '{"active": true, "events": ["package.created", "package.finalized"], "method": "$METHOD", "name": "$NAME", "url": "$URL"}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/custom_webhooks

Response

After a successful request, this endpoint returns 201 Created:

{
  "active": true,
  "body_extras": {
    "key": "value",
    "key2": "value2"
  },
  "events": ["package.created", "package.finalized"],
  "id": "ACHSFSDI32343ASD",
  "headers": {
    "key": "value",
    "key2": "value2"
  },
  "method": "POST",
  "name": "Portal Uploads",
  "url": "https://mywebhooks.endpoint"
}

Update webhook

Authorized users can update custom webhooks under any Team they belong to, subject to the access policy.

Method	Route
`PUT`	`/custom_webhooks/{custom_webhook_id}`

Headers

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key
`Content-Type`	String	Yes	Must be `application/json`

Body

Same fields as the create webhook endpoint above.

Request

curl -d '{"active": true, "events": ["package.created", "package.finalized"], "method": "$METHOD", "name": "$NAME", "url": "$URL"}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/custom_webhooks/$CUSTOM_WEBHOOK_ID

Response

After a successful request, this endpoint returns 200 OK with the updated webhook object.

Delete webhook

Method	Route
`DELETE`	`/custom_webhooks/{custom_webhook_id}`

Headers

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key

Request

curl -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X DELETE https://api.massive.app/v1/custom_webhooks/$CUSTOM_WEBHOOK_ID

Response

Returns 204 No Content. Any transfers in progress at the time of deletion will complete normally.

List webhooks

Method	Route
`GET`	`/teams/{team_id}/custom_webhooks`

Headers

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key

Request

curl -H "X-API-KEY: $API_KEY" \
  -X GET https://api.massive.app/v1/teams/$TEAM_ID/custom_webhooks

Response

Returns 200 OK with an array of webhook objects. The connections property indicates the number of Portals attached to each webhook.

Attach custom webhook to Portal

Custom webhooks can be attached to a Portal on either the Create or Update Portal methods via the custom_webhooks property. The complete list must be passed on every update — any omissions will be removed unless the custom_webhooks property is excluded entirely.

Method	Route
`PUT`	`/portals/{portal_id}`

Headers

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key
`Content-Type`	String	Yes	Must be `application/json`

Body

Name	Type	Required	Description
`custom_webhooks`	Array	No	List of webhook objects with `id` property

Request

curl -d '{"name": "$NAME", "subdomain": "$PORTAL_SUBDOMAIN", "custom_webhooks": [{"id":"$ID1"}, {"id":"$ID2"}], "has_access_code": false, "active": true}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/portals/$PORTAL_ID

List attached webhooks

Retrieve the list of Portals to see their attached custom webhooks.

Method	Route
`GET`	`/teams/{team_id}/portals`

curl -H "X-API-KEY: $API_KEY" \
  -X GET https://api.massive.app/v1/teams/$TEAM_ID/portals

Event payload

Webhook events are sent for successful actions in MASV. The payload follows a standard format with small variations based on the source object. Events are emitted from MASV to each connected webhook and are attempted up to 5 times with an incremental back-off between attempts.

package.created

{
  "event_id": "SFUHDF35DSD88F",
  "event_time": "2021-01-14T10:39:45.334Z",
  "event_type": "package.created",
  "body_extras": {
    "key": "value"
  },
  "object": {
    "type": "package",
    "id": "JF4D076SA6FA1",
    "name": "Sample Upload",
    "portal_id": "01CYCWJC40RXPK3HNQVYKAX1K1",
    "sender": "[email protected]",
    "size": 0,
    "state": "new",
    "total_files": 0,
    "created_at": "2021-01-14T10:39:45.334Z",
    "updated_at": "2021-01-14T10:39:45.334Z"
  },
  "custom_webhook_id": "ACHSFSDI32343ASD"
}

Property	Description
`event_id`	Unique identifier for the webhook event
`event_time`	Timestamp for when the event was generated
`event_type`	Subject of the event (`package.created` or `package.finalized`)
`body_extras`	Key/value pairs supplied on the webhook
`object`	The actual record (a package in this case)
`object.portal_id`	Portal the package was uploaded to (omitted if not a Portal package)
`custom_webhook_id`	Identifier of the webhook this event was associated with

package.finalized

{
  "event_id": "SFUHDF35DSD88F",
  "event_time": "2021-01-14T16:39:56.350Z",
  "event_type": "package.finalized",
  "body_extras": {
    "key": "value"
  },
  "object": {
    "type": "package",
    "id": "JF4D076SA6FA1",
    "name": "Sample Upload",
    "portal_id": "01CYCWJC40RXPK3HNQVYKAX1K1",
    "sender": "[email protected]",
    "size": 33454545,
    "state": "finalized",
    "total_files": 30,
    "created_at": "2021-01-14T10:39:45.334Z",
    "updated_at": "2021-01-14T16:39:56.350Z"
  },
  "custom_webhook_id": "ACHSFSDI32343ASD"
}

The size and total_files fields are populated on the package.finalized event (they are 0 during package.created).