search close

Generic Webhooks

access_time Updated Sep 21, 2021

Our generic webhooks integration allows you to subscribe to notifications for certain activity on Signal Sciences.

Adding a webhook

  1. Go to Site Manage > Site Integrations.
  2. Click Add site integration and select the Generic Webhook integration.
  3. Paste in a URL to receive the notifications and choose which activity you want to trigger the webhook.
  4. Choose whether to receive notifications for all activity or specific activity.
  5. Click Add.

Notifications format

Notifications are sent with the following format:

{
  "created": "2014-12-09T10:43:54-08:00",
  "type": "flag",
  "payload": ...
}

X-SigSci-Signature Header

All requests sent from the generic webhook integration contain a header called X-SigSci-Signature. The value is an HMAC-SHA256 hex digest hashed using a secret key generated when the generic webhook was created.

The key can be rotated by clicking the Edit button next to the generic webhook and then Rotate key in the “Generic webhook integration” form.

Verification is done by creating an HMAC-SHA256 hex digest of the generic webhook payload using the signing key and comparing the result to the value of the X-SigSci-Signature header.

X-SigSci-Signature Header Verification Example Code

Go

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

// CheckMAC reports whether messageMAC is a valid HMAC tag for message.
func CheckMAC(message, messageMAC, key []byte) bool {
	mac := hmac.New(sha256.New, key)
	mac.Write(message)
	expectedMAC := mac.Sum(nil)

	return hmac.Equal(messageMAC, expectedMAC)
}

func main() {
	key := []byte("[insert signing key here]")

	h := "[insert X-SigSci-Signature value here]"

	json := []byte(`[insert JSON payload here]`)

	hash, err := hex.DecodeString(h)
	if err != nil {
		log.Fatal("ERROR: ", err)
	}

	ok := CheckMAC(json, hash, key)

	fmt.Println(ok)
}

Python

import hashlib
import hmac

def checkHMAC(message, messageMAC, key):
    mac = hmac.new(key, message, digestmod=hashlib.sha256).hexdigest()

    return mac == messageMAC

key = '[insert signing key here]'

h = '[insert X-SigSci-Signature value here]'

json = '[insert JSON payload here]'

ok = checkHMAC(json, h, key)

print(ok)

Ruby

require 'openssl'
require "base64"

key = '[insert signing key here]'
h = '[insert X-SigSci-Signature value here]'
json = '[insert JSON payload here]'

hash  = OpenSSL::HMAC.hexdigest('sha256', key, json)

puts hash == h

Bash

#!/bin/bash

function check_hmac {
  json="$1"
  messageMAC="$2"
  key="$3"

  result=$(echo -n "$json" | openssl dgst -sha256 -hmac "$key")
  if [ "$result" == "$messageMAC" ]
  then
          return 0
  else
          return 1
  fi  
}

key='[insert key here]'
h='[insert X-SigSci-Signature value here]'
json='[insert JSON payload here]'

check_hmac "$json" $h $key

Activity types

Activity type Description Payload
siteDisplayNameChanged The display name of a site was changed
siteNameChanged The short name of a site was changed
loggingModeChanged The agent mode (“Blocking”, “Not Blocking”, “Off”) was changed Get site by name
agentAnonModeChanged The agent IP anonymization mode was changed Get site by name
flag An IP was flagged Get event by ID
expireFlag An IP flag was manually expired List events
createCustomRedaction A custom redaction was created Create a custom redactions
removeCustomRedaction A custom redaction was removed Remove a custom redaction
updateCustomRedaction A custom redaction was updated Update a custom redaction
customTagCreated A custom signal was created
customTagUpdated A custom signal was updated
customTagDeleted A custom signal was removed
customAlertCreated A custom alert was created Create a custom alert
customAlertUpdated A custom alert was updated Update a custom alert
customAlertDeleted A custom alert was removed Remove a custom alert
detectionCreated A templated rule was created
detectionUpdated A templated rule was updated
detectionDeleted A templated rule was removed
listCreated A list was created Create a list
listUpdated A list was updated Update a list
listDeleted A list was removed Remove a list
ruleCreated A request rule was created
ruleUpdated A request rule was updated
ruleDeleted A request rule was deleted
customDashboardCreated A custom dashboard was created
customDashboardUpdated A custom dashboard was updated
customDashboardReset A custom dashboard was reset
customDashboardDeleted A custom dashboard was removed
customDashboardWidgetCreated A custom dashboard card was created
customDashboardWidgetUpdated A custom dashboard card was updated
customDashboardWidgetDeleted A custom dashboard card was removed
agentAlert An agent alert was triggered