Vendor webhook notification payloads

When you subscribe to a BILL event and the event triggers, BILL sends a notification to your provided notificationUrl. See /v3/vendors in the API reference for more information about the request and response fields.

Sample vendor.created payload

In this sample unescaped JSON payload, the details of a created vendor are available. The notification includes the vendor id for identifying the vendor in your organization. In addition, createdTime provides the created date and time.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.created",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "{vendor_name}",
        "address" : {
          "country": "US"
        }, 
        "createdTime": "2024-12-15T22:53:15.127+00:00",
        "archived": false
    }
}

Sample vendor.updated payloads

BILL sends vendor.updated notifications for five operations.

Vendor name or address is updated

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification includes the vendor id for identifying the vendor in your organization. In addition, updatedTime provides the updated date and time.

{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "name": "{vendor_name}",
        "updatedTime": "2024-12-16T23:15:15.127+00:00"
    }
}

Vendor connected in the BILL network

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification provides four vendor fields.

FieldDescription
idBILL-generated ID of the vendor. The value begins with 009.
paymentNetworkIdPayment Network ID (PNI) of the connected vendor
networkStatusNetwork connection status. See Connecting with a BILL network vendor for more information.
updatedTimeUpdated date and time
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "paymentNetworkId": "{PNI_id}",
        "networkStatus": "CONNECTED",
        "updatedTime": "2024-12-20T22:55:15.127+00:00"
    }
}

Verified national vendor connected

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification provides four vendor fields.

FieldDescription
idBILL-generated ID of the bill. The value begins with 009.
rppsIdPayment Network ID (PNI) of the connected verified national vendor
networkStatusNetwork connection status. See Connecting with a BILL network vendor for more information.
updatedTimeUpdated date and time
{  
    "metadata": {  
        "eventId": "{event_id}",  
        "subscriptionId": "{subscription_id}",  
        "organizationId": "{organization_id}",  
        "eventType": "vendor.updated",  
        "version": "1"  
    },  
    "vendor": {  
        "id": "{vendor_id}",  
        "rppsId": "{PNI_id}",  
        "networkStatus": "CONNECTED_RPPS",  
        "updatedTime": "2024-02-21T22:55:01.127+00:00"  
    }  
}

Vendor or verified national vendor disconnected

In this sample unescaped JSON payload, the details of an updated vendor are available. The notification provides three vendor fields.

FieldDescription
idBILL-generated ID of the bill. The value begins with 009.
networkStatusNetwork connection status. See Connecting with a BILL network vendor for more information.
updatedTimeUpdated date and time
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.updated",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "networkStatus": "NOT_CONNECTED",
        "updatedTime": "2024-12-21T22:55:01.127+00:00"
    }
}

Sample vendor.archived payload

In this sample unescaped JSON payload, the details of an archived vendor are available. The notification provides three vendor fields.

FieldDescription
idBILL-generated ID of the bill. The value begins with 009.
updatedTimeUpdated date and time
archivedSet as true if the vendor is archived
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.archived",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "updatedTime": "2024-02-25T22:55:01.127+00:00",
        "archived": true
    }
}

Sample vendor.restored payload

In this sample unescaped JSON payload, the details of a restored vendor are available. The notification provides three vendor fields.

FieldDescription
idBILL-generated ID of the bill. The value begins with 009.
updatedTimeUpdated date and time
archivedSet as true if the vendor is archived
{
    "metadata": {
        "eventId": "{event_id}",
        "subscriptionId": "{subscription_id}",
        "organizationId": "{organization_id}",
        "eventType": "vendor.restored",
        "version": "1"
    },
    "vendor": {
        "id": "{vendor_id}",
        "updatedTime": "2024-02-30T22:55:01.127+00:00",
        "archived": false
    }
}