Overview
For webhooks to function properly, template mappings include a required mapping collection for the Message data module.
All inbound webhooks from OpenAI are initially transferred to iPaaS as a Message record before being translated into the appropriate data type (such as Customer).
Do not modify or delete this mapping collection, as it is required for inbound webhook processing.
Before You Begin
Ensure the following prerequisites are in place before configuring this integration.
OpenAI Requirements
OpenAI webhook must be configured to send events to iPaaS.com endpoint.
Webhook payload must include Scope and Id fields for message routing.
Valid webhook secret or API credentials for authentication.
iPaaS.com Requirements
Webhook endpoint URL must be configured and accessible.
This mapping collection must remain enabled and unmodified for webhook processing.
ID Format
Message records are automatically assigned an internal ID when created from webhook payloads. The ID is generated by iPaaS.com and combines the webhook Scope and source Id.
Example: HOOK-12345
Mapping Collection Status
Status: Enabled
Trigger Events: Webhook (Inbound)
Important! Do not disable this mapping collection. It is required for all OpenAI inbound webhook processing. |
Conflicting Mappings
This mapping applies only to Message records created from OpenAI webhooks. This is a prerequisite mapping collection that must exist for other entity-specific mappings (Customer, Product, etc.) to function properly. Do not create duplicate Message mappings for OpenAI webhooks.
Supported Child Collections
This integration does not support any child collections.
Authentication and Security
OpenAI API Key: Used to authenticate requests to the OpenAI API.
Webhook Verification: Before processing an inbound webhook, we validate the webhook key in the header to confirm it originated from OpenAI.
Message Expiration: Messages are assigned an expiration time (30 minutes from creation) to prevent stale webhook data from being processed.
Integration Flow
The integration processes OpenAI webhook messages as follows:
OpenAI sends a webhook event to the iPaaS.com endpoint.
iPaaS.com receives and validates the inbound webhook payload.
A Message record is created with webhook metadata (Scope, Id, Type).
Expiration time is set to 30 minutes from receipt.
Message severity is set to "Info" for standard processing.
The Message record is stored in iPaaS.com for downstream translation.
Subsequent mapping collections translate the Message into the appropriate entity type (Customer, Product, etc.).
Processing status and any errors are logged for troubleshooting.
Mappings
OpenAI Add/Update Message To iPaaS
Description
This mapping collection captures inbound OpenAI webhook data as Message records. The Message serves as an intermediary format that is subsequently translated into specific entity types by downstream mapping collections.
Mapping Type | Source (OpenAI) | Destination (iPaaS) | Description |
Dynamic Formula |
| ExpirationTime | Sets the message expiration to 30 minutes from receipt. Messages not processed before expiration are discarded. |
Static | Info | Severity | Sets the message severity level to "Info" for standard webhook events. |
Dynamic Formula |
| Text | Generates a descriptive message text combining the webhook scope and source identifier for logging and troubleshooting. |
Static | Transfer | Type | Sets the message type to "Transfer" indicating this message contains data for entity translation. |
Error Handling
Webhook Validation Failed
Invalid webhook signature.
Description: The inbound webhook could not be validated as originating from OpenAI.
Resolution: Verify the webhook key is correctly configured in both OpenAI and iPaaS.com. .
Message Expired
Message expiration time exceeded.
Description: The Message record was not processed by downstream mappings before the 30-minute expiration window.
Resolution: Check that downstream mapping collections (Customer, Product, etc.) are enabled and functioning. Review processing logs for errors.
Missing Required Fields
Scope or Id field is null.
Description: The webhook payload is missing required fields for message routing.
Resolution: Verify the OpenAI webhook is configured correctly and sending complete payloads.
Validation and Testing
Before deploying this integration, verify the following configuration items and run the test scenarios to confirm proper operation.
Validation Checklist
This mapping collection is enabled and has not been modified.
Webhook endpoint URL is correctly configured in OpenAI.
API credentials or webhook secret are valid.
Downstream entity mappings (Customer, Product, etc.) are enabled.
Message expiration time allows sufficient processing window.
Test Scenarios
Scenario 1: Valid Webhook Receipt
Send a test webhook from OpenAI. Message record should be created in iPaaS with correct Scope, Id, and ExpirationTime.
Scenario 2: Message Translation
Send a webhook and verify the Message is subsequently translated into the correct entity type by downstream mappings.
Scenario 3: Invalid Webhook (Failure Case)
Send a webhook with invalid signature. Webhook should be rejected; error should be logged.
Scenario 4: Expiration Handling
Create a Message and allow it to expire without processing. Verify expired messages are handled appropriately.
Additional Notes
Do not delete or disable this mapping collection. It is required for all OpenAI webhook processing.
This mapping creates intermediate Message records; actual entity creation/updates occur in separate mapping collections.
The 30-minute expiration window can be adjusted by modifying the AddMinutes() value, but shorter windows may cause processing failures under high load.
Message records serve as an audit trail for webhook activity and can be used for troubleshooting integration issues.
The "Transfer" type indicates the message contains data intended for translation into another entity type.