Webhooks

Webhooks Overview

SalesMagic offers webhooks to notify you in real-time when certain events happen in your account. Webhooks are HTTPS requests made to an endpoint of your choice that you can then implement custom business logic for. For example, you can receive a webhook when a call is completed by one of your sales reps with associated analysis and details of the call. Your endpoint that receives this webhook can then process the payload of the webhook to automate some internal process or data insight, such as updating records in your LMS, or custom reporting needs.

Webhook Events

When configuring webhooks, you will subscribe to one or more events within SalesMagic which you wish to be notified of and process data from. The current list of supported events are available here. They are also available within the webhook management settings when configuring your endpoint(s).

How to implement webhooks

At a high level, in order to implement webhooks, you'll need to:

• Register the URL you wish to receive the webhooks using the management portal.
• Implement the registered URL as a public POST endpoint on your servers that accepts the webhook payload. This endpoint should verify the signature of the request to make sure the webhook is from SalesMagic, and handle the relevant pieces of payload you need and then perform your business logic.

To configure webhook integration, begin by going to the Account Settings section in SalesMagic and enabling your webhook integration:

Once enabled, you can begin to set up your endpoints and subscribe to one or more event types to begin processing data.

Management Portal

In order to start listening to messages, you will need to configure your endpoints. Adding an endpoint is as simple as providing a URL that you control and selecting the event types that you want to listen to.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type. This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving extraneous messages.

If your endpoint isn't quite ready to start receiving events, you can press the "with Svix Play" button to have a unique URL generated for you. You'll be able to view and inspect webhooks sent to your Svix Play URL, making it effortless to get started.

Testing

Once you've added an endpoint, you'll want to make sure its working. The "Testing" tab lets you send test events to your endpoint. After sending an example event, you can click into the message to view the message payload, all of the message attempts, and whether it succeeded or failed.

Verifying Signatures

Webhook signatures let you verify that webhook messages are actually sent by us and not a malicious actor. For a more detailed explanation, check out this article on why you should verify webhooks.

Our webhook partner Svix offers a set of useful libraries that make verifying webhooks very simple.

Retries

We attempt to deliver each webhook message based on a retry schedule with exponential backoff.

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

• Immediately
• 5 seconds
• 5 minutes
• 30 minutes
• 2 hours
• 5 hours
• 10 hours
• 10 hours (in addition to the previous)

If an endpoint is removed or disabled, delivery attempts to the endpoint will be disabled as well. For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

Manual retries: You can also use the application portal to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.

Failure Recovery

Re-enable a disabled endpoint: If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. To re-enable a disabled endpoint, go to the webhook dashboard, find the endpoint from the list and select "Enable Endpoint".

Recovering/Resending failed messages:

If your service has downtime or if your endpoint was misconfigured, you probably want to recover any messages that failed during the downtime.

If you want to replay a single event, you can find the message from the UI and click the options menu next to any of the attempts. From there, click "resend" to have the same message send to your endpoint again.

If you need to recover from a service outage and want to replay all the events since a given time, you can do so from the Endpoint page. On an endpoint's details page, click "Options > Recover Failed Messages". From there, you can choose a time window to recover from.

For a more granular recovery - for example, if you know the exact timestamp that you want to recover from - you can click the options menu on any message from the endpoint page.

From there, you can click "Replay..." and choose to "Replay all failed messages since this time."

Troubleshooting Tips

There are some common reasons why your webhook endpoint is failing:

• Not using the raw payload body: This is the most common issue. When generating the signed content, we use the raw string body of the message payload. If you convert JSON payloads into strings using methods like stringify, different implementations may produce different string representations of the JSON object, which can lead to discrepancies when verifying the signature. It's crucial to verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification.

• Missing the secret key: From time to time we see people simple using the wrong secret key. Remember that keys are unique to endpoints.

• Sending the wrong response codes: When we receive a response with a 2xx status code, we interpret that as a successful delivery even if you indicate a failure in the response payload. Make sure to use the right response status codes so we know when message are supposed to succeed vs fail.

• Responses timing out: We will consider any message that fails to send a response within {timeout duration} a failed message. If your endpoint is also processing complicated workflows, it may timeout and result in failed messages.

We suggest having your endpoint simply receive the message and add it to a queue to be processed asynchronously so you can respond promptly and avoiding getting timed out.