Skip to content

Webhooks

Introduction to OLC webhooks

Open Letter Connect (OLC) uses webhooks to notify your system about significant events that occur on the platform. For example, when a new order is created, OLC will send a notification to your system to inform you of the event. This ensures your systems are always synchronized, allowing you to automate processes efficiently and take action in real time.

OLC webhooks provide seamless integration with external systems, allowing you to receive updates such as order creations, template updates, and more, as they happen. This document outlines the available webhook events, their descriptions, purposes, and the parameters associated with each event.

Benefits of Using Webhooks

  • Real-Time Updates: Receive notifications about events as they occur.
  • Reduced Latency: Push notifications eliminate the need for constant polling.
  • Automation: Trigger automated workflows based on specific events.

This document provides detailed information about the webhook events available, including their descriptions, purposes, parameters involved in each event, and best practices for implementation.

Configuration

For detailed instructions on how to set up webhooks with Open Letter Connect, please refer to our Webhook Configuration Guide . This guide will walk you through creating an endpoint.

Authentication Details

To secure your webhooks, use authentication methods such as:

  • Webhook Secret Keys: Use secret key to authenticate your webhook payloads. Keep the secret key confidential.
  • Custom Headers: You can also include as many custom headers as needed to implement additional authentication mechanisms.

Security Considerations

  1. Use HTTPS: Ensure that your webhook endpoint is served over HTTPS to protect data in transit from eavesdropping or tampering.
  2. Token Verification: Implement a mechanism to verify webhook secret token to ensure that requests are genuinely from Open Letter Connect. This involves checking a token included in the webhook payload against your secret key.
  3. IP Whitelisting: If possible, whitelist the IP addresses from which Open Letter Connect sends webhooks to prevent unauthorized access. If you need to know our IP addresses for this purpose, please feel free to contact us.

Webhook Retries

If your server fails to respond successfully (e.g., returns a 404 or 500 HTTP status code), Open Letter Connect will retry sending the webhook notification. The retry logic works as follows:

  • Response Codes: Successful responses (e.g., 200 OK) will stop further retries. Any error responses will trigger additional attempts.

Event Overview Section

Here are the different events that can trigger webhooks in Open Letter Connect:

Each event has its own payload structure and purpose, as described below.

Handling Events

  1. Idempotency: Design your webhook processing logic to be idempotent. This means that processing the same webhook multiple times should not lead to unintended side effects (e.g., duplicate orders).
  2. Error Handling: Implement robust error handling to manage failed webhook deliveries. Return appropriate HTTP status codes:
  3. 200 OK for successful processing.
  4. 400 Bad Request for malformed requests.
  5. 500 Internal Server Error for server issues.
  6. Logging: Maintain logs of received webhooks and their processing outcomes. This will help in troubleshooting issues and understanding webhook behavior over time.

Common Issues and Troubleshooting

Here are some common integration problems and solutions:

  • Webhook Not Received:

    • Ensure your endpoint URL is correctly configured and accessible from the internet.
    • Check Webhook Logs on Open Letter Connect against your webhook.
    • Check server logs for any incoming requests or errors.

  • Invalid Payload Structure:

    • Verify that your endpoint can correctly parse JSON payloads and handle all expected parameters.

  • Authentication Errors:

    • Double-check your token verification logic and ensure secret keys are correctly implemented.

Contact Information for Support

If you encounter issues or have questions about webhook integration, please reach out to our support team at [email protected]