Webhooks – Sideqik

Use webhooks to be notified about events that happen in your Sideqik account.

Webhook Overview

An event is an account occurrence, such an influencer submitting an application, being approved, or updating their profile. Each occurrence has a corresponding Event object.

Webhook endpoints are URLs defined by users to which Sideqik sends events.

Webhooks allow your services to be notified when events occur without having to make an API request by letting you register a URL that we will notify anytime an event happens. When the event occurs - for example, when an influencer profile is modified, Sideqik creates an Event object containing the relevant information, including the type of event and data associated with that event. Sideqik then sends the Event object to your account's webhook URL via an HTTP POST request.

Enabling Webhooks in Sideqik

Webhooks are enabled and configured under your Account Settings on the Integrations page. Clicking “Enable Integration” on API Integration opens a form where you can set the URL for receiving webhooks as well as which events you want to receive.

You can enter any URL you'd like to have events sent to, but this should be a dedicated page on your server, coded per the instructions below.

You can also choose to be notified of all event types, or only specific ones.

Note that you must be on the Enterprise plan to use webhooks. Need to upgrade? Contact sales@sideqik.com

Receiving a Webhook Notification

Creating a webhook endpoint is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object.

Ruby Sinatra Example

require "json"

post "/sideqik/webhook/url" do

# Retrieve the request's body and parse it as JSON

event_json = JSON.parse(request.body.read)

# Do something with event_json

status 200

end

Receiving webhooks with a CSRF-protected server

If you're using Rails, Django, or another web framework, your site may automatically check that every POST request contains a CSRF token. This is an important security feature that helps protect you and your users from cross-site request forgery attempts. However, this security measure may also prevent your site from processing legitimate webhooks. If so, you may need to exempt the webhooks route from CSRF protection.

Ruby on Rails Example

class WebhookController < ApplicationController

# If your controller accepts requests other than Sideqik webhooks,

# you'll probably want to use `protect_from_forgery` to add CSRF

# protection for your application. But don't forget to exempt

# your webhook route!

protect_from_forgery :except => :webhook

def webhook

# Process webhook data in `params`

end

end

Receiving Webhooks with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Sideqik will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Responding to a Webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside the this range, including 3xx codes, will indicate that you did not receive the webhook. To be clear, URL redirections or "Not Modified" responses will be treated as failures.

If a webhook is not successfully received for any reason, Sideqik will continue trying to send it once an hour for up to 3 days. Webhooks cannot be manually retried after this time, though you can query for the event to reconcile your data with any missed events.

You can check webhooks that we’ve sent and how many times we've attempted to send an event to an endpoint by clicking View Events from your Webhook integration. This will show you a list of all attempted webhooks and the HTTP status codes we received.

Best Practices

Before going live, test your webhook is working properly. You can do so by sending dummy test events from the Webhooks integration pane. Understand that as these are fake events that will not map to real influencers in your account.

If your webhook script performs complex logic, or makes network calls, it's possible your script will timeout before Sideqik sees its complete execution. For that reason, you may want to have your webhook endpoint immediately acknowledge receipt by returning a 2xx HTTP status code, and then perform the rest of its duties.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events.

Webhook Event Types

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn't rely on only these types existing in your code.:

influencer.created
influencer.updated
influencer.deleted
fan.entered
fan.updated

For an example of the [INFLUENCER ENTITY] below, see our REST Documentation.

Event: influencer.created

Occurs whenever an influencer is created. For example, this occurs when an influencer is imported, submits an application, or is added manually.