Webhooks

Event reference

Every event CueDM sends, when it fires, and the exact payload your endpoint receives.

Overview

Each delivery has the same shape: id, event, workspaceId, occurredAt and data. What's in data depends on the event, as listed below. A webhook only receives the events it subscribes to, plus ping when you send a test.

dm.sentDM sent: An automation sent a DM.
dm.failedDM failed: Instagram refused a DM an automation tried to send.
link.clickedLink clicked: A tracked link in a DM was opened.
contact.createdNew contact: A person reached one of your accounts for the first time.
contact.email_capturedEmail captured: Someone replied to an automation with their email.
bio.subscribedBio page signup: Someone left their email on your bio page.
bio.unsubscribedBio page unsubscribe: A bio page subscriber unsubscribed.

dm.sent

An automation sent someone a DM.

data.automation.idstring: The automation that sent it.
data.automation.namestring: Its name in CueDM.
data.account.idstring: The Instagram account's ID in CueDM.
data.account.usernamestring: The account's Instagram handle, without the @.
data.account.instagramIdstring: The account's ID at Instagram.
data.user.idstring: The person's Instagram-scoped ID.
data.user.usernamestring | null: Their handle, when Instagram shares it.
data.sourcestring: Where it started: COMMENT, DM, STORY_REPLY, STORY_MENTION, LIVE_COMMENT or REF_LINK.
data.textstring: What they wrote: the comment, reply or message.
data.matchedKeywordstring | null: The keyword that matched, or null when the automation replies to everything.
data.variantnumber | null: Which version of the message was sent in an A/B test: 0 for the main message, 1 and up for the alternatives. Null when the automation has no test.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "dm.sent",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:00:00.000Z",
  "data": {
    "automation": {
      "id": "auto_sample",
      "name": "Spring bundle"
    },
    "account": {
      "id": "acct_sample",
      "username": "yourbrand",
      "instagramId": "17841400000000000"
    },
    "user": {
      "id": "1234567890",
      "username": "maya.fits"
    },
    "source": "COMMENT",
    "text": "LINK please",
    "matchedKeyword": "LINK",
    "variant": null
  }
}

dm.failed

An automation tried to send a DM and Instagram refused it, for example because the person doesn't accept messages from the account. Useful for alerting someone to reply by hand.

data.automation.idstring: The automation that sent it.
data.automation.namestring: Its name in CueDM.
data.account.idstring: The Instagram account's ID in CueDM.
data.account.usernamestring: The account's Instagram handle, without the @.
data.account.instagramIdstring: The account's ID at Instagram.
data.user.idstring: The person's Instagram-scoped ID.
data.user.usernamestring | null: Their handle, when Instagram shares it.
data.sourcestring: Where it started: COMMENT, DM, STORY_REPLY, STORY_MENTION, LIVE_COMMENT or REF_LINK.
data.textstring: What they wrote: the comment, reply or message.
data.matchedKeywordstring | null: The keyword that matched, or null when the automation replies to everything.
data.variantnumber | null: Which version of the message was sent in an A/B test: 0 for the main message, 1 and up for the alternatives. Null when the automation has no test.
data.errorstring: Why it failed, in words.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "dm.failed",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:00:00.000Z",
  "data": {
    "automation": {
      "id": "auto_sample",
      "name": "Spring bundle"
    },
    "account": {
      "id": "acct_sample",
      "username": "yourbrand",
      "instagramId": "17841400000000000"
    },
    "user": {
      "id": "1234567890",
      "username": "maya.fits"
    },
    "source": "COMMENT",
    "text": "LINK please",
    "matchedKeyword": "LINK",
    "variant": null,
    "error": "The person has not allowed messages from this account"
  }
}

link.clicked

A tracked link from a DM was opened. It fires for every open, including repeat clicks and link previews some apps fetch, and it doesn't say who clicked: use it for counts, not to attribute a click to a person.

data.automation.idstring: The automation whose DM carried the link.
data.link.idstring: The tracked link.
data.link.slugstring: Its short code in cuedm.com/r/<slug>.
data.link.destinationUrlstring: Where it sends people, before UTM tags are added.
data.variantnumber | null: The A/B variant the link belongs to, or null.
data.referrerstring | null: The Referer header the browser sent, if any.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "link.clicked",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:05:00.000Z",
  "data": {
    "automation": {
      "id": "auto_sample"
    },
    "link": {
      "id": "link_sample",
      "slug": "k3j9x",
      "destinationUrl": "https://yourstore.com/product"
    },
    "variant": null,
    "referrer": null
  }
}

contact.created

CueDM saw a person for the first time on one of your accounts: their first comment, reply or message. It fires once for each person on each account.

data.contact.idstring: The contact in CueDM.
data.contact.igUserIdstring: Their Instagram-scoped ID.
data.contact.usernamestring | null: Their handle, when known.
data.contact.accountIdstring: The Instagram account in CueDM they reached.
data.contact.sourcestring | null: Where it started: COMMENT, DM, STORY_REPLY, STORY_MENTION, LIVE_COMMENT or REF_LINK.
data.contact.automationIdstring | null: The automation that met them, if any.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "contact.created",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:00:00.000Z",
  "data": {
    "contact": {
      "id": "contact_sample",
      "igUserId": "1234567890",
      "username": "maya.fits",
      "accountId": "acct_sample",
      "source": "COMMENT",
      "automationId": "auto_sample"
    }
  }
}

contact.email_captured

An automation asked someone for their email and they replied with one. The address is lowercased.

data.contact.idstring: The contact in CueDM.
data.contact.igUserIdstring: Their Instagram-scoped ID.
data.contact.usernamestring | null: Their handle, when known.
data.contact.emailstring: The address they sent.
data.contact.accountIdstring: The Instagram account in CueDM.
data.contact.automationIdstring: The automation that asked.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "contact.email_captured",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:02:00.000Z",
  "data": {
    "contact": {
      "id": "contact_sample",
      "igUserId": "1234567890",
      "username": "maya.fits",
      "email": "maya@example.com",
      "accountId": "acct_sample",
      "automationId": "auto_sample"
    }
  }
}

bio.subscribed

Someone left their email in a form on your bio page. It fires once for each address. Sending the same address again doesn't fire it again.

data.subscriber.idstring: The signup.
data.subscriber.emailstring: The address they left.
data.subscriber.answersobject: Answers to the form's other fields, keyed by field ID. Empty when there are none.
data.subscriber.marketingConsentboolean: Whether they ticked the opt-in to marketing email.
data.subscriber.subscribedAtstring: When they signed up.
data.subscriber.unsubscribeUrlstring: Their own unsubscribe link. Put it in every email you send them: using it removes them in CueDM and sends you bio.unsubscribed.
data.page.idstring: The bio page.
data.page.slugstring: Its address, cuedm.me/<slug>.
data.page.titlestring: Its title.
data.form.idstring: The form on the page.
data.form.labelstring: The form's label.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "bio.subscribed",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:10:00.000Z",
  "data": {
    "subscriber": {
      "id": "sub_sample",
      "email": "maya@example.com",
      "answers": {},
      "marketingConsent": true,
      "subscribedAt": "2026-09-21T10:10:00.000Z",
      "unsubscribeUrl": "https://cuedm.me/yourbrand/unsubscribe/0123456789abcdef0123456789abcdef"
    },
    "page": {
      "id": "page_sample",
      "slug": "yourbrand",
      "title": "Your Brand"
    },
    "form": {
      "id": "form_sample",
      "label": "Join the list"
    }
  }
}

bio.unsubscribed

Someone used their unsubscribe link. Remove the address from any list you copied it to.

data.subscriber.idstring: The signup, as in bio.subscribed.
data.subscriber.emailstring: The address.
data.subscriber.unsubscribedAtstring: When they unsubscribed.
data.page.idstring: The bio page.
data.page.slugstring: Its address.
data.page.titlestring: Its title.

Example body

{
  "id": "cmg4x0x6d0001l50g8m2k1v7q",
  "event": "bio.unsubscribed",
  "workspaceId": "cmfz8o3gq0000l50gk3ah2d9e",
  "occurredAt": "2026-09-21T10:12:00.000Z",
  "data": {
    "subscriber": {
      "id": "sub_sample",
      "email": "maya@example.com",
      "unsubscribedAt": "2026-09-21T10:12:00.000Z"
    },
    "page": {
      "id": "page_sample",
      "slug": "yourbrand",
      "title": "Your Brand"
    }
  }
}

ping

Sent by Send test in Settings, to that one webhook only. Answer it like any other event. If you route events by name, make sure an unknown name gets a 2xx too and doesn't fail the delivery.

data.messagestring: Hello from CueDM

Stuck, or something here is wrong? Email support@cuedm.com and a person will answer.