Consuming Hi Marley Webhooks

How do we use Webhooks?

APIs are used to request actions like updating, deleting, or retrieving information, while webhooks automatically send relevant data to our customers. APIs are great for retrieving information on demand, but they require a request each time you need data.

Webhooks, on the other hand, continuously listen for updates and push information in real time. For example, we use webhooks for events like the send message trigger, allowing customer messages to be received instantly—without repeatedly requesting updates.

What do I Need to Consume Webhooks?

To consume incoming webhooks, you’ll need to set up and configure a system that can receive, process, and respond to the data payload sent by Hi Marley. Here’s a checklist of the key requirements:

An Active and Accessible URL Endpoint

• Requirement: A public-facing URL that can receive incoming HTTP requests from Hi Marley
  • This endpoint can be hosted on traditional in-house servers or cloud platforms (e.g., AWS Lambda, Azure, Google Cloud Functions).
  • Must anticipate different HTTP methods (POST, GET, PUT) depending on which webhooks you have subscribed - more information can be found in our Webhook Guides.

Application Server/Backend System

• Requirement: A server-side application to process the incoming webhook data.
  • Server should be running and actively listening for requests at all times.
  • Common frameworks for webhooks include: Node.js (Express), Python (Flask/Django), Java (Spring Boot), or Ruby (Rails).

Whitelist Information

• Requirement: Organizations must whitelist specific Hi Marley endpoints for API's, SFTP, and Webhooks.
  • Webhooks require a select number of static IP's to be whitelisted in your firewall, as well as a media URL domain.
  • Specific information can be found in our Whitelist Information Guide.

Data Format Handling 

• Requirement: Must have the ability to parse and process the payload sent by the webhook.
  • Hi Marley webhooks will deliver payloads in JSON.
  • Depending on which webhooks you have subscribed, JSON payload data must be parsed for specific records - see our Webhook Guides for more information.

Event Handling Logic

• Requirement: Ability to perform desired actions after Webhook event is received and parsed for specific variables.
  • Map different types of events to specific handlers (e.g. 'opt_in', 'message_updated', 'case_event').
  • Validate incoming data to ensure it adheres to expected schema.

Response Mechanism

• Requirement: Consumers of Hi Marley webhooks send a response to confirm successful receipt.
  • In the event of outage outside of Hi Marley, data in the carrier systems will become out of sync with Hi Marley.
  • Send appropriate HTTP response codes:
    • 200 OK for successful processing.
      4xx or 5xx for errors (see Retry Failed Webhooks for more information).
  • If your organization has a queuing system implemented to log failed inbound API requests, then the Webhook Retry APIs can be leveraged to implement into your retry/queuing system and reprocess any failed inbound requests.

Logging and Monitoring

• Requirement: Implement logging and monitoring to track incoming requests and potential errors.
  • Useful for troubleshooting, debugging, and ensuring the webhook is operating as expected.
  • Monitoring provides real-time alerts on failures or anomalies, improving reliability and performance.

Scalability 

• Requirement: Ensure the ability to handle fluctuating volumes of incoming requests, especially during unexpected surges in business.
  • Implement rate-limiting policies to prevent denial-of-service (DoS) attacks or service overload.
  • Use queues (e.g., AWS SQS, Redis) to handle incoming requests during spikes.

Webhook Authentication 

• Optional: Hi Marley supports both basic authorization tokens and OAuth 2.0 to prevent from unauthorized access.
  • The Hi Marley webhooks can be configured to send static basic auth tokens to your system. This token can be subscribed as a part of the header.
  • Hi Marley webhooks support Oauth 2.0 for outbound authorization integrations with any system that accepts Oauth 2.0.
  • For more information, see our Webhook Authentication Documentation.

By addressing the above requirements, you can reliably consume and process incoming webhooks from Hi Marley, ensuring seamless integration, improved performance, and a more efficient workflow. Proper implementation enhances system stability, reduces errors, and enables real-time data processing for a better overall experience.