Webhook Payload Reference

Before your ERP system sends back the vendor number, B1Link first sends a webhook payload to your configured webhook receiver endpoint. This section documents the complete structure of the incoming payload that B1Link will POST to your endpoint.

Structure

The payload sent from B1Link to your ERP system follows this structure:

{
  "onboardingRequestErpEventId": "550e8400-e29b-41d4-a716-446655440000",
  "clientCompanyId": 123,
  "supplierCompanyId": 456,
  "workflowInstanceId": "660e8400-e29b-41d4-a716-446655440001",
  "data": [
    {
      "category": "OnboardingRequestDetails",
      "dataJson": { /* Onboarding request details */ },
      "success": true,
      "errorMessage": null
    },
    {
      "category": "CompanyDetails",
      "dataJson": { /* Company information */ },
      "success": true,
      "errorMessage": null
    },
    {
      "category": "BbbeeInfo",
      "dataJson": { /* B-BBEE information */ },
      "success": true,
      "errorMessage": null
    },
    {
      "category": "Documents",
      "dataJson": { "documents": [ /* Document status array */ ] },
      "success": true,
      "errorMessage": null
    }
  ]
}

Payload Field Descriptions

Field	Type	Description
onboardingRequestErpEventId	GUID (string)	Unique identifier for the onboarding request ERP event
clientCompanyId	integer	The ID of the client company requesting the onboarding
supplierCompanyId	integer	The ID of the supplier company being onboarded
workflowInstanceId	GUID (string)	The workflow instance ID tracking this onboarding process
data	array	Array of collected data items, each with a category and dataJson

Data Category Types

Each item in the data array contains:

Field	Type	Description
category	string	One of: OnboardingRequestDetails, CompanyDetails, BbbeeInfo, Documents
dataJson	object or array	The actual data for this category (structure varies by category)
success	boolean	Whether the data was successfully retrieved
errorMessage	string or null	Error message if data retrieval failed

Important Notes

1. Data Categories: Not all categories may be present in every payload. Categories are included based on what data is available and configured for the specific onboarding request.

2. Success Status: Each data item has its own success status. A category with success: false will have an errorMessage explaining the failure.

3. DataJson Structure: The dataJson field structure varies by category:

   • OnboardingRequestDetails: Object with onboarding request information (see OnboardingRequestDetailsDataDto)
   • CompanyDetails: Object with comprehensive company information (see IntegrationGatewayCompanyDetailsDataDto)
   • BbbeeInfo: Object with B-BBEE certificate and ownership details (see IntegrationGatewayBbbeeInfoDataDto)
   • Documents: Object with a documents property containing an array of document status objects (see IntegrationGatewayDocumentsDataDto)

4. Type Safety: All dataJson fields use strongly typed DTOs with camelCase property naming. This ensures consistent structure and type safety across all webhook payloads.

5. Null Values: Many fields may be null if data is not available or not applicable.

6. Webhook Receiver Configuration: This payload is POSTed by B1Link to your configured webhook receiver endpoint URL. Ensure your endpoint can handle this structure and respond appropriately (typically with a 200 OK status).

Complete Example

See the Complete Example Payload for a full example with all data categories populated.

Next Steps

• Complete Example Payload - Full example with all fields
• Integration Guide - How to send vendor numbers back to B1Link