Webhooks

Connect your MASV account to external web services to receive notifications via custom webhooks.

Note

This feature is only available for a limited number of customers. To request webhooks API access for your Team, please contact support@masv.io.

Create webhook

You can create custom webhooks for any Team you 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

# Store your API key in an environment variable — never hardcode it.
# See /api/api-keys/ for key management best practices.
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

Caution

The total size of URL + headers + extras + event payload cannot exceed 128 KiB. HTTPS endpoints must have a valid TLS 1.2 or 1.3 certificate.

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"
}

Note

Webhook endpoints must use HTTPS with a valid TLS certificate. HTTP endpoints are not supported.

Update webhook

You can update custom webhooks for any Team you 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 are 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

Note

When updating Portals, provide the full Portal object. The following example is a reference for adding custom webhooks only.

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

Caution

All attached custom webhooks must be provided in each PUT request or they are removed.

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": "test@masv.io",
    "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": "test@masv.io",
    "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).

Security considerations

MASV webhooks do not currently include a cryptographic signature for payload verification. To secure your webhook endpoint:

• Use HTTPS — All webhook URLs must use HTTPS with a valid TLS certificate.
• Use the headers field — Include a shared secret as a custom header when creating the webhook. Validate this header on your receiving endpoint to confirm the request originated from MASV.
• Restrict by IP — If your infrastructure supports it, allowlist MASV’s outbound IP ranges.
• Validate the payload structure — Check that event_type, custom_webhook_id, and object.id are present and well-formed before processing.