Webhooks

Current Support

We currently support webhooks for:

• Data Models: Files, Folders, Drawings, RFIs, Submittals, Specification Sections, and Vendors (at the Company and Project-level).
• Events: Create, Update, and Delete
• Source Systems: Procore

To request other webhooks, reach out to us at api-support@agaveapi.com.

API Endpoint

To learn more about requests that are supported, see Webhooks.

https://api.agaveapi.com/webhooks

Request Header

As with other API requests, you need to include an API-Version, Client-Id, Client-Secret, Account-Token, and (optionally) Project-Id. To learn more, see Headers.

Body Parameters

Key	Type	Description	Example	Required
callback_url	String	The URL to send events to. You can generate a callback URL from webhook.site for testing and change it to your own server's endpoint to receive events.	"https://webhook.site/#!/58eb2c6a-2fce-4e61-88ad-c9a354819737"	Required
authorization_header	String	If provided, all webhooks POST requests delivered by Agave will contain this Authorization information in the request header	"Bearer 9tk5GuTqqcOt7P0spZ7fJZoN8eqtYx" or "Basic S3CRET!" or empty	Optional
event	String	The event to subscribe to.	"CREATE", "UPDATE", or "DELETE"	Required
type	String	The type of data to subscribe to.	"file", "folder", "rfi", "submittal", "vendor", etc.	Required

Example Request

curl --request POST https://api.agaveapi.com/webhooks \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: procore_account_token' \
     --header 'Include-Source-Data: true' \
     --header 'Project-Id: your_optional_project_id' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "callback_url": "https://your-website.com/webhook-callback",
            "authorization_header": "Bearer 9tk5GuTqqcOt7P0spZ7fJZoN8eqtYx"
            "event": "CREATE",
            "type": "file"
        }'

Response

Body Parameters

Key	Type	Description
source_id	String	The ID of the event in the Source System.
callback_url	String	The URL you specified in the request to send events to.
event	String	The event you specified in the request to subscribe to.
project_id	String	The UUID of the Project assigned by Agave.
target	String	The ID that you can use to tie events back to what's in your system. This includes the webhook event type (e.g. "file"), followed by either the Agave-generated UUID for a specific data object or a "*" for all data objects for the requested type.
type	String	The type of data you specified in the request to subscribe to.

Example Response

{
    "id": "8c6309d7-4d44-517b-a5e0-42ff993d7b08",
    "source_id": "198402",
    "callback_url": "https://your-website.com/webhook-callback",
    "event": "CREATE",
    "project_id": "your_optional_project_id",
    "target": "file:*",
    "type": "file"
}

Example Webhook Event

This is an example webhook event that Agave will asynchronously send to your registered callback endpoint. Note that the project_id and target fields have been converted to Agave UUIDs.

If you provided an authorization_header header when creating the webhook, all events delivered by Agave will include it as the Authorization header.

{
    "id": "04b38725-31ea-5682-adfe-ac1ac38f5713",
    "source_id": "198396",
    "callback_url": "https://your-website.com/webhook-callback",
    "event": "CREATE",
    "project_id": "2c20934e-98c0-522b-a730-80571d02f8be",
    "target": "bdc00643-a562-5bcf-9c85-daf58bda3012",
    "type": "file",
    "source_data": {
        "path": "",
        "content_type": "application/json",
        "data": {
            "user_id": 77742,
            "ulid": "01FXRACPEGBXAPKN9B58CBGK7A",
            "timestamp": "2022-03-09T21:47:03.193658Z",
            "resource_name": "Project Files",
            "resource_id": 9741901,
            "project_id": 66736,
            "metadata": {
                "source_user_id": 77742,
                "source_project_id": 66736,
                "source_operation_id": null,
                "source_company_id": 31936,
                "source_application_id": null
            },
            "id": 277215374,
            "event_type": "create",
            "company_id": 31936,
            "api_version": "v2"
        }
    }
}