dispatch.

Documentation

Webhooks

A webhook tells another service when one of your posts is published or fails, so nothing has to keep asking.

What webhooks are for

When a post reaches a destination, or fails to, Dispatch sends a small signed request to a URL you choose. Use it to start whatever comes next: an auto-reply tool, a row in a spreadsheet, a message in a chat channel, or your own script. A webhook hears only about your own posts.

Add a webhook

  1. Sign in and open Settings → Webhooks, then choose Add webhook.
  2. Give it a name and the URL that should receive the events.
  3. Choose the events. You can also limit it to some platforms or some of your accounts; with none ticked it hears about all of them.
  4. If the receiving service gave you a signing secret, paste it. If you leave the field blank, Dispatch makes a secret and shows it once, for you to copy into the receiver.

Send test sends a webhook.test event straight away and shows what the receiver answered. Deliveries lists the last 50 deliveries, each with its answer, and can send one again.

You can have up to 10 webhooks. Tests and repeated deliveries are limited to 10 a minute between them; past that Dispatch asks you to wait until the minute is over.

Events

EventWhen it is sent
post.publishedA destination is confirmed published. Once for each destination.
post.failedA destination stops on a failure, or needs review. Not sent for each automatic retry.
webhook.testYou chose Send test.

A post that goes to three accounts sends three events, one for each destination.

The payload

The body is JSON. This is a post.published event:

{
  "type": "post.published",
  "timestamp": "2026-11-12T18:00:04.120Z",
  "data": {
    "post": {
      "id": "3f2b8c1e-7a4d-4e0b-9c55-1d2e3f4a5b6c",
      "title": "A quiet morning",
      "caption": "Taking the long way home.",
      "scheduled_at": "2026-11-12T18:00:00.000Z"
    },
    "destination": {
      "id": "8d1e6a52-0c3b-4f7e-a1d9-5b6c7d8e9f01",
      "platform": "instagram",
      "state": "published",
      "remote_id": "17900000000000000",
      "url": "https://www.instagram.com/reel/EXAMPLE/",
      "published_at": "2026-11-12T18:00:03.000Z",
      "message": "Published on Instagram",
      "error_code": null,
      "account": {
        "id": "c2a9f7d4-5e61-4b38-8f0a-9e8d7c6b5a41",
        "remote_id": "17841400000000000",
        "username": "yourhandle",
        "name": "Your Name"
      }
    },
    "reel": null,
    "integrations": {}
  }
}

destination.url is the link to the post on the platform, when the platform gives one. In a post.failed event, destination.state is failed or needs_review, and message and error_code say what happened. integrations carries the settings stored on the post for the services that receive it, such as Replybeam below. reel is always null. A test event has only data.webhook, with the webhook’s id and name.

Verify the signature

Every request is signed the Standard Webhooks way, so the receiver can tell it came from Dispatch and was not changed. Three headers carry it:

webhook-id: msg_2f6c0d1e9a8b4c7d8e9f0a1b2c3d4e5f
webhook-timestamp: 1794506404
webhook-signature: v1,<base64 signature>

The signature is the base64 HMAC-SHA256 of id.timestamp.body, with the three joined by full stops. The key is your signing secret without whsec_, decoded from base64. Sign the body exactly as it arrived, before parsing it. webhook-id stays the same on every retry of a delivery, so you can use it to ignore a repeat.

Node

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is the request body exactly as it arrived, before any JSON parsing.
export function verifyDispatchWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  // Refuse anything more than five minutes old.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(age <= 300)) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    const given = Buffer.from(signature || "", "base64");
    return (
      version === "v1" &&
      given.length === expected.length &&
      timingSafeEqual(given, expected)
    );
  });
}

Python

import base64
import hashlib
import hmac
import time


def verify_dispatch_webhook(secret: str, headers, raw_body: bytes) -> bool:
    """raw_body is the request body exactly as it arrived, as bytes."""
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures:
        return False
    try:
        age = abs(time.time() - int(timestamp))
    except ValueError:
        return False
    if age > 300:  # refuse anything more than five minutes old
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature.encode(), expected):
            return True
    return False

Libraries for Standard Webhooks do the same check, if you would rather not write it.

Retries and timeouts

An answer with a 2xx status means the delivery arrived. Dispatch waits 30 seconds for it. A timeout, a network error, or an answer of 408, 429 or 5xx is tried again after 30 seconds, 1 minute, 2 minutes, 5 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours and 8 hours: 12 attempts over about 24 hours. A Retry-After header on your answer is respected when it asks for longer. Any other answer is final, and redirects are not followed. Answer quickly and do slow work afterwards.

URL rules

Dispatch’s server makes the request, so the URL has to lead to the public internet:

  • https:// only, without a username or password in it. Any port is fine.
  • Not localhost, and not a private, loopback or link-local address.
  • The hostname is looked up again before every attempt. If it leads to a private or local address, the delivery fails and is not retried.

Send posts to Replybeam

Replybeam is our other product: it answers Instagram comments with a DM. Dispatch can hand it an Instagram post as it goes out, so the reply is ready before the first comment arrives. This needs a Replybeam Pro account. Instagram has to be connected there too.

  1. In Dispatch, open Settings → Replybeam and choose Connect Replybeam.
  2. Replybeam opens, asks you to sign in if you aren’t, and says what connecting does. Choose Connect Dispatch. You come back to Dispatch’s Settings, which now says Connected.
  3. When you write a post for Instagram, open After it’s posted → Reply to comments with Replybeam in the composer. Write the keyword people will comment and the DM they should get.

When Instagram confirms the post, Dispatch sends post.published with those settings in integrations.replybeam, and Replybeam sets the reply up and switches it on. You connect once, then fill in the composer for each post that should have a reply.

Connecting adds a webhook named Replybeam to your list, for Instagram’s post.published event. It is one of your 10 webhooks, and you can test it, see its deliveries and turn it off like any other. Connecting again replaces it. Disconnect removes it from Dispatch. Dispatch can’t remove Replybeam’s side of it, so remove the webhook named Dispatch in Replybeam’s settings too.

By hand

You can also set the same thing up yourself:

  1. In Replybeam, open Settings and create an incoming webhook. Replybeam gives you a URL and a signing secret.
  2. In Dispatch, open Settings → Webhooks and add a webhook. Paste that URL and that secret, and keep Post published ticked.

Settings shows a webhook you added this way as connected too.