{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks","description":"Guides and API reference for the DataSift (REISift) Core API and SiftMap API."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks push DataSift events to your own systems as they happen, so you don't have to poll. Use them to feed a CRM, a dialer or SMS tool, an automation platform (Zapier, Make, n8n, Pipedream), an AI agent, or your own backend."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["outbound"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["account-level"]},". DataSift sends an HTTPS ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," with a JSON body to an endpoint you control."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You add a webhook in the DataSift app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sequence Builder"]},", you add the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send a webhook"]}," action and pick that webhook."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each time a sequence reaches that action for a property, DataSift sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence.action.triggered"]}," event to your endpoint with the sequence and property context."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Combine the webhook action with other sequence actions, for example \"status changed to ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Hot Lead"]},"\" → send a webhook ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["and"]}," create a follow-up task."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types","__idx":2},"children":["Event types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it's sent"},"children":["When it's sent"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence.action.triggered"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A sequence reached a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send a webhook"]}," action for a property."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.test"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You sent a test delivery from the app. Dummy data in the same shape as a real event."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["More event types will be added over time; see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/changelog"},"children":["changelog"]},". Your endpoint should ignore event types it does not handle."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-up-a-webhook-in-the-app","__idx":3},"children":["Set up a webhook in the app"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create the receiving endpoint in your tool (for example, a Zapier \"Catch Hook\" or an n8n Webhook node) and copy its URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In DataSift, go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings → Integrations → Webhooks"]}," and select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add Webhook"]},". Enter a name, paste the URL, and save."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test"]}," to send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.test"]}," delivery and confirm your endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sequence Builder"]},", add the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send a webhook"]}," action to a sequence, and choose your webhook from the list. Only active webhooks are listed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add and manage webhooks in the DataSift app before you add the action to a sequence. Creating and managing webhooks requires the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Super Admin"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sensei"]}," role; anyone with access to Sequence Builder can use an existing webhook in a sequence."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authenticate-datasift-to-your-endpoint","__idx":4},"children":["Authenticate DataSift to your endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your endpoint requires a credential, configure it when setting up the webhook in the DataSift app. DataSift sends it with every delivery:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"auth.type"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth.type"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fields you send"},"children":["Fields you send"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header DataSift sends"},"children":["Header DataSift sends"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}," (default)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["none"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["none"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["basic"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["username"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Basic <base64 of username:secret>"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bearer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <secret>"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["header"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<header>: <secret>"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verify-that-a-delivery-came-from-datasift","__idx":5},"children":["Verify that a delivery came from DataSift"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every delivery is signed with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ed25519"]},". Verifying is optional, but it's the only way to know a request really came from DataSift and wasn't modified."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Sift-Webhook-Signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1,7mJ2...=="]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signature version, then the base64 Ed25519 signature"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Sift-Webhook-Timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1786742400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unix seconds when the delivery was signed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Sift-Webhook-Key-Id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["k1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which public key verifies the signature"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The signature covers this exact byte string:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{timestamp}.{raw_request_body}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw request body"]}," as received. Parsing and re-serializing the JSON changes key order and whitespace, and the signature won't match."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get the public keys from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET https://apiv2.reisift.io/webhook/signing-keys/"]}," (no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header). Pick the key whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_id"]}," matches the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Sift-Webhook-Key-Id"]}," header, cache the response, and refetch when you see a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key_id"]}," you don't have. During a key rotation both keys are returned, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["additional"]},"; treat both as valid."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"keys\": [\n    {\n      \"key_id\": \"k1\",\n      \"algorithm\": \"ed25519\",\n      \"status\": \"active\",\n      \"public_key\": \"-----BEGIN PUBLIC KEY-----\\n...\\n-----END PUBLIC KEY-----\\n\"\n    }\n  ],\n  \"signature_header\": \"X-Sift-Webhook-Signature\",\n  \"timestamp_header\": \"X-Sift-Webhook-Timestamp\",\n  \"key_id_header\": \"X-Sift-Webhook-Key-Id\",\n  \"signed_payload_format\": \"{timestamp}.{raw_request_body}\",\n  \"signature_version\": \"v1\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Node.js:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const crypto = require(\"crypto\");\n\nconst [version, signature] = req.headers[\"x-sift-webhook-signature\"].split(\",\");\nconst timestamp = Number(req.headers[\"x-sift-webhook-timestamp\"]);\n\nconst ok = crypto.verify(\n  null, // Ed25519 takes no separate digest\n  Buffer.concat([Buffer.from(`${timestamp}.`), req.rawBody]),\n  crypto.createPublicKey(publicKeyPem),\n  Buffer.from(signature, \"base64\"),\n);\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Python:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import base64\nfrom cryptography.exceptions import InvalidSignature\nfrom cryptography.hazmat.primitives.serialization import load_pem_public_key\n\nversion, _, signature = headers[\"X-Sift-Webhook-Signature\"].partition(\",\")\ntimestamp = int(headers[\"X-Sift-Webhook-Timestamp\"])\n\ntry:\n    load_pem_public_key(public_key_pem.encode()).verify(\n        base64.b64decode(signature),\n        f\"{timestamp}.\".encode() + raw_body,\n    )\nexcept InvalidSignature:\n    reject()\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The timestamp is part of the signed string, so a captured delivery can't be re-dated. Reject deliveries whose timestamp is too old; allow at least 15 minutes so retries still pass."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payload","__idx":6},"children":["Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each delivery is a JSON object with event metadata, the sequence that fired, and the property the action ran for. Illustrative example (values are fictitious):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event_type\": \"sequence.action.triggered\",\n  \"event_id\": \"1b9f0c2e-6a51-4c8e-9f3d-2f1e7c4a9b10\",\n  \"event_datetime\": \"2026-11-02T14:05:31Z\",\n  \"sequence\": {\n    \"uuid\": \"6c0b1d8a-2f4e-4a7b-9c1d-3e5f7a9b1c2d\",\n    \"name\": \"Absentee Owner Follow-up\"\n  },\n  \"property\": {\n    \"uuid\": \"73e52854-ebb2-55a3-8768-f78cf98a4897\",\n    \"address\": {\"street\": \"123 Main St\", \"city\": \"Columbus\", \"state\": \"OH\", \"postal_code\": \"43207\"},\n    \"owner\": {\"first_name\": \"Jane\", \"last_name\": \"Doe\"},\n    \"tags\": [\"FTM\"],\n    \"lists\": [\"Foreclosure 2026-07\"]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The property object carries the same fields as the record in the API. Use the app's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test"]}," button to see the exact payload for your account, and build your parser to ignore fields it doesn't know so new fields don't break it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-and-retries","__idx":7},"children":["Delivery and retries"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Respond with any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," status within a few seconds. Do slow work after you respond (queue it)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A failed delivery (network error, timeout, or non-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]},") is retried up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3 times"]}," with exponential backoff. If your endpoint returns a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header, DataSift honors it for up to 15 minutes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A failed delivery never stops the rest of the sequence."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deliveries can arrive more than once or out of order. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_id"]}," to skip duplicates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deliveries are rate-capped per account to protect your endpoint and the platform."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":8},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Check"},"children":["Check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test fails"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The URL is HTTPS and public, the endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]},", and any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["auth"]}," credential is current."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signature never matches"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You verify against the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw"]}," body, include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{timestamp}."]}," prefix, and use the key matching ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Sift-Webhook-Key-Id"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No deliveries"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The webhook is enabled, the sequence is active, and its trigger and conditions match your records."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duplicates"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deduplicate on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_id"]},"."]}]}]}]}]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Event types","id":"event-types","depth":2},{"value":"Set up a webhook in the app","id":"set-up-a-webhook-in-the-app","depth":2},{"value":"Authenticate DataSift to your endpoint","id":"authenticate-datasift-to-your-endpoint","depth":2},{"value":"Verify that a delivery came from DataSift","id":"verify-that-a-delivery-came-from-datasift","depth":2},{"value":"Payload","id":"payload","depth":2},{"value":"Delivery and retries","id":"delivery-and-retries","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2}],"frontmatter":{"seo":{"title":"Webhooks"}},"lastModified":"2026-11-01T21:43:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}