@sentdm/sentdm 0.38.0 → 0.40.0

package/src/resources/webhooks.ts

@@ -336,6 +336,454 @@ export interface APIResponseWebhook {
   success?: boolean;
 }
 
+/**
+ * The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+ * this shape and varies only in Payload.
+ */
+export interface ChannelEvent {
+  /**
+   * The specific event within the family, for example message.delivered,
+   * message.received or contact.opt_out. Absent on events that have no subtype, so
+   * treat it as optional.
+   */
+  event?: string | null;
+
+  /**
+   * The event family, for example message, templates or contact. Route on this
+   * first, then on event for the specific change.
+   */
+  field?: string;
+
+  /**
+   * Body of a channel event: where one of the customer's channels stands in
+   * provisioning and compliance. Delivered when a milestone moves — a registration
+   * filed, a verdict returned, a resubmission asked for, a sender gone live — so a
+   * customer's own onboarding UI does not have to poll GET /v3/channels.
+   *
+   * The subject is one item, never the account. A customer's "SMS channel" has no
+   * status; a market does. Country, NumberType and SenderValue name which one, so a
+   * customer terminating only to Kosovo never receives an event about US 10DLC.
+   *
+   * Status is the stable half of the contract. It is the same four-value set GET
+   * /v3/channels publishes, computed through the same code, so an event and a read
+   * of the same market cannot disagree. A subscriber that reads nothing but the
+   * status and the subject fields is a correct subscriber. The sub-type on the
+   * envelope names the specific milestone and is additive — that vocabulary comes
+   * from registries and carriers, which are parties Sent does not control.
+   *
+   * Status means provisioning and compliance are complete, not that a send will
+   * succeed right now. An account can be suspended, or a destination blocked by a
+   * routing rule, without either showing up here. Those are separate surfaces and
+   * deliberately not modelled on this payload.
+   */
+  payload?: ChannelEventPayload | null;
+
+  /**
+   * The event-specific body.
+   */
+  request_id?: string | null;
+
+  /**
+   * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+   * time, not the time the underlying change happened. Use the timestamp inside the
+   * payload for the latter.
+   */
+  timestamp?: string;
+}
+
+/**
+ * Body of a channel event: where one of the customer's channels stands in
+ * provisioning and compliance. Delivered when a milestone moves — a registration
+ * filed, a verdict returned, a resubmission asked for, a sender gone live — so a
+ * customer's own onboarding UI does not have to poll GET /v3/channels.
+ *
+ * The subject is one item, never the account. A customer's "SMS channel" has no
+ * status; a market does. Country, NumberType and SenderValue name which one, so a
+ * customer terminating only to Kosovo never receives an event about US 10DLC.
+ *
+ * Status is the stable half of the contract. It is the same four-value set GET
+ * /v3/channels publishes, computed through the same code, so an event and a read
+ * of the same market cannot disagree. A subscriber that reads nothing but the
+ * status and the subject fields is a correct subscriber. The sub-type on the
+ * envelope names the specific milestone and is additive — that vocabulary comes
+ * from registries and carriers, which are parties Sent does not control.
+ *
+ * Status means provisioning and compliance are complete, not that a send will
+ * succeed right now. An account can be suspended, or a destination blocked by a
+ * routing rule, without either showing up here. Those are separate surfaces and
+ * deliberately not modelled on this payload.
+ */
+export interface ChannelEventPayload {
+  /**
+   * The market's destination country as an ISO 3166-1 alpha-2 code, for example XK.
+   * Always present, and the property that identifies this payload among the
+   * delivered envelopes — see DeliveredWebhookEvents. Every event in this family
+   * reports one market, and a market has a country.
+   */
+  country: string;
+
+  /**
+   * The account whose market this is, named as on every other family. When an
+   * organization receives an event for one of its sender profiles this is the
+   * profile, so a reseller compares it with its own id and anything different is one
+   * of its profiles. Matches customer_id on GET /v3/channels and the sender
+   * profile's id. Together with channel, country, and number_type, it identifies the
+   * market.
+   */
+  account_id?: string;
+
+  /**
+   * The channel this market belongs to: sms, whatsapp, or rcs. Never sent — that
+   * value belongs to message events, where it names the smart-routing brand rather
+   * than a channel that can be provisioned.
+   */
+  channel?: string;
+
+  /**
+   * What a market has been given: the identity it registers under, its programme,
+   * and any documents attached.
+   *
+   * What it does not carry is what the market asks for. That is the subject of GET
+   * /v3/compliance/requirements, and it is the same answer for every caller — a
+   * description of what a compliance regime wants, not a record of one customer's
+   * progress through it. It was reported here as well for a while, which put the
+   * same array in six response shapes and left a caller deciding which of two
+   * sources to believe.
+   *
+   * Present on a list read for markets that register (carrying brand and campaign),
+   * but with documents absent — documents are not fetched for a list, because a
+   * catalog lookup and a document read per market would multiply across a page.
+   * Absent documents is distinct from an empty list: absent says they were not
+   * fetched; empty says the market has been given none. The parent object is null
+   * only when the market registers with nobody and compliance was not computed —
+   * nothing to show at all.
+   */
+  compliance?: ChannelEventPayload.Compliance | null;
+
+  /**
+   * The kind of sender the market uses, for example TEN_DLC, LOCAL, or ALPHANUMERIC.
+   * Omitted when the subject has no sender type of its own.
+   */
+  number_type?: string | null;
+
+  /**
+   * Why the market reached this state, when a reason was given — a correction
+   * explained, or a campaign lapse. Free text, passed through from the registry or
+   * carrier that wrote it, so treat it as a message to show a human rather than a
+   * value to branch on.
+   */
+  reason?: string | null;
+
+  /**
+   * The sender itself — a number in E.164, or an alphanumeric sender ID.
+   *
+   * Always present, and null until a sender exists. The key is on every delivery so
+   * a subscriber reads one shape rather than branching on whether the field arrived
+   * — the same choice template_id makes on the message payload.
+   *
+   * It can carry a value at any point in the lifecycle, not only once the market is
+   * live: a number ordered and not yet active at the carrier is already known during
+   * PROVISIONING, and an alphanumeric sender the customer chose themselves is known
+   * before anything is filed. It is null while the market is still waiting on a
+   * number, which for a US 10DLC registration is every event up to
+   * channel.activated.
+   */
+  sender_value?: string | null;
+
+  /**
+   * Where the market stands: PENDING_REVIEW, ACTION_NEEDED, PROVISIONING, ACTIVE or
+   * INACTIVE. PENDING_REVIEW means a registry or a carrier holds it and the wait is
+   * theirs; ACTION_NEEDED means it is yours; PROVISIONING means the verdict is in
+   * and Sent is acquiring the sender; INACTIVE means it had a working sender and no
+   * longer does.
+   *
+   * Each event name is the transition into one of these, but the two are separate
+   * fields and may legitimately differ. A resubmission filed against a market whose
+   * sender is already live is channel.submitted carrying ACTIVE: a correction is
+   * with the registry and the sender keeps working. Read both.
+   */
+  status?: string;
+
+  /**
+   * When the transition happened, in UTC (yyyy-MM-ddTHH:mm:ssZ).
+   */
+  updated_at?: string;
+}
+
+export namespace ChannelEventPayload {
+  /**
+   * What a market has been given: the identity it registers under, its programme,
+   * and any documents attached.
+   *
+   * What it does not carry is what the market asks for. That is the subject of GET
+   * /v3/compliance/requirements, and it is the same answer for every caller — a
+   * description of what a compliance regime wants, not a record of one customer's
+   * progress through it. It was reported here as well for a while, which put the
+   * same array in six response shapes and left a caller deciding which of two
+   * sources to believe.
+   *
+   * Present on a list read for markets that register (carrying brand and campaign),
+   * but with documents absent — documents are not fetched for a list, because a
+   * catalog lookup and a document read per market would multiply across a page.
+   * Absent documents is distinct from an empty list: absent says they were not
+   * fetched; empty says the market has been given none. The parent object is null
+   * only when the market registers with nobody and compliance was not computed —
+   * nothing to show at all.
+   */
+  export interface Compliance {
+    /**
+     * The identity this market registers under, with inherit saying whose it is.
+     *
+     * Reported here rather than on the profile because it belongs to the registration
+     * this market files, and only one market files one. It was a top-level block for a
+     * while, which put a per-registration value beside a list of markets and left a
+     * caller to work out which market it belonged to.
+     *
+     * Absent for a market that registers with nobody — such a market asks for no
+     * identity, so there is none to report. Absent and null mean different things:
+     * absent says this market does not ask, null would say it asks and nothing was
+     * supplied.
+     *
+     * Untyped, like the request side, because its members are declared by the market's
+     * own schema rather than by a C# class. A typed pair here would be a second
+     * definition of what a market wants, free to drift from the one that validates.
+     */
+    brand?: { [key: string]: unknown } | null;
+
+    /**
+     * The programme this market registers, with inherit saying whose it is.
+     *
+     * One, not a list. TcrCampaigns permits several and an account built on the admin
+     * side may hold them, but this surface offers one — which is what lets the
+     * market's PATCH be an upsert rather than a collection with an addressable create
+     * behind it. An account holding several is reported as its first and refused on
+     * write, rather than half-edited.
+     *
+     * Carries no id. Nothing addresses a campaign, and an undeclared key would be
+     * refused if the caller sent this object back — which it is meant to be able to
+     * do.
+     */
+    campaign?: { [key: string]: unknown } | null;
+
+    /**
+     * What has been supplied for this market.
+     *
+     * Files, not values — the declared halves above carry the values. A document
+     * cannot be a JSON value, so it is sent as multipart on the channel call and
+     * reported here as a reference.
+     *
+     * Absent on a list read, which fetches identity but does not compute compliance
+     * documents per market. Absent and empty mean different things: absent says the
+     * documents were not fetched; empty says the market has been given none.
+     */
+    documents?: Array<Compliance.Document> | null;
+  }
+
+  export namespace Compliance {
+    /**
+     * A document a market asked for and has been given.
+     */
+    export interface Document {
+      /**
+       * Identifier of the upload, for fetching it back through the documents endpoints.
+       */
+      document_id?: string | null;
+
+      file_name?: string | null;
+
+      /**
+       * The catalog's name for this document, matching the requirement it satisfies.
+       */
+      key?: string;
+    }
+  }
+}
+
+/**
+ * The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+ * this shape and varies only in Payload.
+ */
+export interface ContactEvent {
+  /**
+   * The specific event within the family, for example message.delivered,
+   * message.received or contact.opt_out. Absent on events that have no subtype, so
+   * treat it as optional.
+   */
+  event?: string | null;
+
+  /**
+   * The event family, for example message, templates or contact. Route on this
+   * first, then on event for the specific change.
+   */
+  field?: string;
+
+  /**
+   * Body of a contact.opt_in, contact.opt_out, contact.help or
+   * contact.custom_keyword event. Delivered when a contact signals a consent change,
+   * asks for help, or sends one of your own auto-reply keywords.
+   *
+   * These events state the signal outright, so you do not have to recognise keywords
+   * in the text of a message.received event. They also cover cases that produce no
+   * inbound message at all, such as a network handling an opt-out on your behalf.
+   *
+   * Two of the four change consent and two do not: contact.help and
+   * contact.custom_keyword report the state the contact already had. Read opt_out
+   * for the state and the envelope's event for what happened, rather than inferring
+   * one from the other.
+   *
+   * Fields are ordered identity → resulting state → provenance → join keys. The two
+   * parties are from and to. Note that the message family has not moved to those
+   * names yet — message.received still calls the same two parties inbound_number and
+   * outbound_number. Nothing here restates the envelope: which signal occurred is
+   * the envelope's event, and when it was emitted is its timestamp. Retries carry
+   * the same X-Webhook-Event-ID header, which is what to deduplicate on.
+   */
+  payload?: ContactEventPayload | null;
+
+  /**
+   * The event-specific body.
+   */
+  request_id?: string | null;
+
+  /**
+   * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+   * time, not the time the underlying change happened. Use the timestamp inside the
+   * payload for the latter.
+   */
+  timestamp?: string;
+}
+
+/**
+ * Body of a contact.opt_in, contact.opt_out, contact.help or
+ * contact.custom_keyword event. Delivered when a contact signals a consent change,
+ * asks for help, or sends one of your own auto-reply keywords.
+ *
+ * These events state the signal outright, so you do not have to recognise keywords
+ * in the text of a message.received event. They also cover cases that produce no
+ * inbound message at all, such as a network handling an opt-out on your behalf.
+ *
+ * Two of the four change consent and two do not: contact.help and
+ * contact.custom_keyword report the state the contact already had. Read opt_out
+ * for the state and the envelope's event for what happened, rather than inferring
+ * one from the other.
+ *
+ * Fields are ordered identity → resulting state → provenance → join keys. The two
+ * parties are from and to. Note that the message family has not moved to those
+ * names yet — message.received still calls the same two parties inbound_number and
+ * outbound_number. Nothing here restates the envelope: which signal occurred is
+ * the envelope's event, and when it was emitted is its timestamp. Retries carry
+ * the same X-Webhook-Event-ID header, which is what to deduplicate on.
+ */
+export interface ContactEventPayload {
+  /**
+   * Whether the contact is opted out after this signal — the state to write to your
+   * own record. Same meaning as opt_out on the contact resource. On contact.help and
+   * contact.custom_keyword this reports the contact's existing state, which neither
+   * changes.
+   *
+   * Two signals from the same contact can arrive out of order, because each one is
+   * queued on its own rather than against the contact. Compare the envelope's
+   * timestamp before you overwrite a newer state with an older one. That timestamp
+   * is second-precision, so treat two signals stamped in the same second as
+   * unordered and read the contact resource to settle them.
+   */
+  opt_out: boolean;
+
+  /**
+   * How the signal reached us. INBOUND_KEYWORD means the contact sent a message
+   * whose text matched one of the keywords; PROVIDER_SIGNAL means the network
+   * reported it. A provider signal usually carries no message_id or text, so read
+   * both for null rather than inferring them from this field.
+   */
+  source: string;
+
+  /**
+   * The account the contact belongs to. Present so one endpoint can serve several
+   * accounts.
+   */
+  account_id?: string;
+
+  /**
+   * The RCS agent the signal reached, when it reached one.
+   *
+   * Omitted entirely on channels that have no agent, rather than sent as null — an
+   * SMS or WhatsApp payload does not carry this key at all. On RCS it is the
+   * counterpart to To: a contact reaches an agent rather than a number, so exactly
+   * one of the two is populated and never both. If you run more than one agent, this
+   * is what tells you which of them the contact acted on.
+   */
+  agent_id?: string | null;
+
+  /**
+   * The channel the signal arrived on, for example sms or whatsapp.
+   */
+  channel?: string;
+
+  /**
+   * The contact who raised the signal. Always populated, including for contact.help
+   * or contact.custom_keyword from a number you have not messaged before — the
+   * contact is created if it does not exist yet, so this identifier is always
+   * resolvable against the contacts API.
+   */
+  contact_id?: string;
+
+  /**
+   * The contact's number, in E.164 format with the leading + — who raised the
+   * signal. The same party message.received publishes as inbound_number.
+   */
+  from?: string;
+
+  /**
+   * The inbound message that carried the signal, matching message_id on the
+   * corresponding message.received event so the two can be joined.
+   *
+   * Sent as null when the signal did not arrive as a message — for example when a
+   * network processed an opt-out on your behalf — and also when the message belongs
+   * to a different account than this event, which can happen on a shared WhatsApp
+   * number. The field is always present, so read it and check for null rather than
+   * checking whether the key exists.
+   */
+  message_id?: string | null;
+
+  /**
+   * The auto-reply template whose keyword the contact matched, joinable against the
+   * templates API.
+   *
+   * This is what identifies which signal arrived on contact.custom_keyword: every
+   * custom template reports the same event name, so the event alone cannot tell your
+   * booking keyword from your opening-hours one. One template holds as many keywords
+   * as you configured, so this is steadier to switch on than text.
+   *
+   * Populated on the compliance sub-types too, where it names the template that
+   * replied. Sent as null when no template was involved — a network-reported opt-out
+   * matches no keyword. The field is always present, so read it and check for null.
+   */
+  template_id?: string | null;
+
+  /**
+   * The text the contact sent, for example STOP or UNSUBSCRIBE. Sent as null when
+   * the signal did not arrive as text. The field is always present, so read it and
+   * check for null rather than checking whether the key exists.
+   */
+  text?: string | null;
+
+  /**
+   * The number of yours that received the signal, in E.164 format with the leading
+   * +. Tells a multi-number account which of its senders the contact acted on, which
+   * nothing else on this payload answers.
+   *
+   * This is your number, not the contact's. That is the opposite of what to means on
+   * POST /v3/messages, where it is the list of recipients you are sending to. Reply
+   * to From, not to this field, or the message goes back to yourself.
+   *
+   * Sent as null when the signal did not arrive at a number of yours — an RCS signal
+   * terminates at an agent rather than a number, and a provider-reported opt-out may
+   * name no receiving number at all. The field is always present, so read it and
+   * check for null rather than checking whether the key exists.
+   */
+  to?: string | null;
+}
+
 /**
  * Error information
  */
@@ -367,15 +815,15 @@ export interface ErrorDetail {
  */
 export interface InboundMessageEvent {
   /**
-   * The specific event within the family, for example message.delivered or
-   * message.received. Absent on events that have no subtype, so treat it as
-   * optional.
+   * The specific event within the family, for example message.delivered,
+   * message.received or contact.opt_out. Absent on events that have no subtype, so
+   * treat it as optional.
    */
   event?: string | null;
 
   /**
-   * The event family, for example message or templates. Route on this first, then on
-   * event for the specific change.
+   * The event family, for example message, templates or contact. Route on this
+   * first, then on event for the specific change.
    */
   field?: string;
 
@@ -385,6 +833,11 @@ export interface InboundMessageEvent {
    */
   payload?: InboundMessageEventPayload | null;
 
+  /**
+   * The event-specific body.
+   */
+  request_id?: string | null;
+
   /**
    * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
    * time, not the time the underlying change happened. Use the timestamp inside the
@@ -448,15 +901,15 @@ export interface InboundMessageEventPayload {
  */
 export interface MessageEvent {
   /**
-   * The specific event within the family, for example message.delivered or
-   * message.received. Absent on events that have no subtype, so treat it as
-   * optional.
+   * The specific event within the family, for example message.delivered,
+   * message.received or contact.opt_out. Absent on events that have no subtype, so
+   * treat it as optional.
    */
   event?: string | null;
 
   /**
-   * The event family, for example message or templates. Route on this first, then on
-   * event for the specific change.
+   * The event family, for example message, templates or contact. Route on this
+   * first, then on event for the specific change.
    */
   field?: string;
 
@@ -467,6 +920,11 @@ export interface MessageEvent {
    */
   payload?: MessageEventPayload | null;
 
+  /**
+   * The event-specific body.
+   */
+  request_id?: string | null;
+
   /**
    * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
    * time, not the time the underlying change happened. Use the timestamp inside the
@@ -498,6 +956,13 @@ export interface MessageEventPayload {
    */
   agent_id?: string | null;
 
+  /**
+   * The rendered message body, as plain text. Sent as null when we aren't asserting
+   * a body for this event. The field is always present, so read it and check for
+   * null rather than checking whether the key exists. Truncated to 3072 characters.
+   */
+  body?: string | null;
+
   /**
    * The channel the message went out on, for example sms or whatsapp. A message that
    * falls back to another channel reports the channel actually used.
@@ -515,6 +980,19 @@ export interface MessageEventPayload {
    */
   outbound_number?: string;
 
+  /**
+   * message.scheduled only: why the message is held, either because you scheduled it
+   * or because the recipient is inside a protected quiet-hours window. Omitted on
+   * every other event.
+   */
+  schedule_reason?: string | null;
+
+  /**
+   * message.scheduled only: when the held message will be released for delivery, in
+   * UTC (yyyy-MM-ddTHH:mm:ssZ). Omitted on every other event.
+   */
+  scheduled_at?: string | null;
+
   /**
    * The template the message was sent from, when it was sent from one.
    */
@@ -598,15 +1076,15 @@ export namespace PaginationMeta {
  */
 export interface TemplateEvent {
   /**
-   * The specific event within the family, for example message.delivered or
-   * message.received. Absent on events that have no subtype, so treat it as
-   * optional.
+   * The specific event within the family, for example message.delivered,
+   * message.received or contact.opt_out. Absent on events that have no subtype, so
+   * treat it as optional.
    */
   event?: string | null;
 
   /**
-   * The event family, for example message or templates. Route on this first, then on
-   * event for the specific change.
+   * The event family, for example message, templates or contact. Route on this
+   * first, then on event for the specific change.
    */
   field?: string;
 
@@ -616,6 +1094,11 @@ export interface TemplateEvent {
    */
   payload?: TemplateEventPayload | null;
 
+  /**
+   * The event-specific body.
+   */
+  request_id?: string | null;
+
   /**
    * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
    * time, not the time the underlying change happened. Use the timestamp inside the
@@ -645,15 +1128,39 @@ export interface TemplateEventPayload {
    */
   account_id?: string;
 
+  /**
+   * Which consent keyword this template answers, when it is one of Sent's
+   * auto-replies: OPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.
+   *
+   * Omitted for an ordinary template, so its presence is the answer to "is this an
+   * auto-reply". Sent creates the three compliance auto-replies at signup and they
+   * go through review like any other template, so their events arrive mixed in with
+   * the customer's own with nothing else to tell them apart.
+   *
+   * Named for the reader rather than after Template.OptAction, which it is mapped
+   * from. The MCP tool result deliberately keeps OptAction, OptKeywords and IsOpt:
+   * it mirrors the internal shape on purpose and publishes the keywords too, so
+   * renaming one of the three there would leave a surface half in each vocabulary.
+   * Two names for one concept, each consistent within its own surface, chosen over a
+   * rename that breaks MCP clients silently.
+   */
+  auto_reply_action?: string | null;
+
   /**
    * The template's category, for example UTILITY, MARKETING, or AUTHENTICATION.
    */
   category?: string;
 
   /**
-   * The channel the template applies to.
+   * The channel leg this decision is about, for example whatsapp, sms, or rcs. A
+   * template is reviewed per channel and the legs come back independently, so each
+   * one reports separately.
+   *
+   * Omitted when the decision applies to the template as a whole rather than to one
+   * leg. That event is the broader news: a template-wide rejection blocks every
+   * channel, whatever the individual legs say.
    */
-  channel?: string;
+  channel?: string | null;
 
   /**
    * The template's language code, for example en_US.
@@ -782,11 +1289,30 @@ export interface WebhookListEventsResponse {
 
   /**
    * The exact event body that was delivered, or attempted, for this record. One of
-   * the three webhook envelopes: a message status change, an inbound message, or a
-   * template status change. Read field and event to tell which, the same way your
-   * endpoint does.
-   */
-  event_data?: MessageEvent | InboundMessageEvent | TemplateEvent;
+   * the six webhook envelopes:
+   *
+   * message — an outbound message changed status. message with event:
+   * message.received — someone replied to you. templates — a template was approved,
+   * rejected, paused or similar. channel — one of your markets moved in provisioning
+   * or compliance. contact — a consent signal: opt-in, opt-out or help. link — a
+   * tracked short link was clicked or a hosted file downloaded, or one expired or
+   * was revoked.
+   *
+   * Read field and event to tell which, the same way your endpoint does. The two
+   * message envelopes are the reason that is two fields and not one: they share a
+   * field and differ by event.
+   *
+   * Treat the list as open. It has grown twice — channel and then link — and a
+   * handler that rejects an envelope it does not recognise will break on the next
+   * addition rather than ignore it.
+   */
+  event_data?:
+    | MessageEvent
+    | InboundMessageEvent
+    | TemplateEvent
+    | ChannelEvent
+    | ContactEvent
+    | WebhookListEventsResponse.SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload;
 
   event_type?: string;
 
@@ -799,6 +1325,218 @@ export interface WebhookListEventsResponse {
   response_body?: string | null;
 }
 
+export namespace WebhookListEventsResponse {
+  /**
+   * The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+   * this shape and varies only in Payload.
+   */
+  export interface SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload {
+    /**
+     * The specific event within the family, for example message.delivered,
+     * message.received or contact.opt_out. Absent on events that have no subtype, so
+     * treat it as optional.
+     */
+    event?: string | null;
+
+    /**
+     * The event family, for example message, templates or contact. Route on this
+     * first, then on event for the specific change.
+     */
+    field?: string;
+
+    /**
+     * Body of a link event: something happened to a tracked link Sent published on the
+     * customer's behalf. A link points either at a URL the customer supplied or at a
+     * file Sent hosts for them; LinkKind says which. Delivered when an eligible
+     * request is served, or when a published link reaches the end of its life.
+     *
+     * A click is a request, not a read receipt. link.clicked means the redirect was
+     * served; link.downloaded means bytes went out. Neither proves a person saw
+     * anything — messaging providers and link scanners fetch URLs on their own, which
+     * is what TrafficClass exists to tell apart. Filter on it before reporting a
+     * click-through rate; treat likely_human as a hint, never as delivery
+     * confirmation.
+     *
+     * RecordId identifies the link; the X-Webhook-Event-ID header identifies the
+     * delivery. One link is hit many times, so those are the two keys a subscriber
+     * needs: group by the first, deduplicate on the second — exactly as on every other
+     * family. The payload carries no event identifier of its own, for the same reason
+     * none of the others do.
+     *
+     * Nothing here identifies the visitor. No IP address and no visitor token crosses
+     * this boundary. Country, Device and Browser are coarse buckets derived at the
+     * edge and are absent whenever the request did not supply enough to derive them.
+     */
+    payload?: SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload.Payload | null;
+
+    /**
+     * The event-specific body.
+     */
+    request_id?: string | null;
+
+    /**
+     * When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+     * time, not the time the underlying change happened. Use the timestamp inside the
+     * payload for the latter.
+     */
+    timestamp?: string;
+  }
+
+  export namespace SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload {
+    /**
+     * Body of a link event: something happened to a tracked link Sent published on the
+     * customer's behalf. A link points either at a URL the customer supplied or at a
+     * file Sent hosts for them; LinkKind says which. Delivered when an eligible
+     * request is served, or when a published link reaches the end of its life.
+     *
+     * A click is a request, not a read receipt. link.clicked means the redirect was
+     * served; link.downloaded means bytes went out. Neither proves a person saw
+     * anything — messaging providers and link scanners fetch URLs on their own, which
+     * is what TrafficClass exists to tell apart. Filter on it before reporting a
+     * click-through rate; treat likely_human as a hint, never as delivery
+     * confirmation.
+     *
+     * RecordId identifies the link; the X-Webhook-Event-ID header identifies the
+     * delivery. One link is hit many times, so those are the two keys a subscriber
+     * needs: group by the first, deduplicate on the second — exactly as on every other
+     * family. The payload carries no event identifier of its own, for the same reason
+     * none of the others do.
+     *
+     * Nothing here identifies the visitor. No IP address and no visitor token crosses
+     * this boundary. Country, Device and Browser are coarse buckets derived at the
+     * edge and are absent whenever the request did not supply enough to derive them.
+     */
+    export interface Payload {
+      /**
+       * The link's public identifier — the eight-character code in the short URL, for
+       * example A78B2BU0. Unique across both kinds, and never reused, so it is the
+       * stable key to group one link's events by.
+       */
+      record_id: string;
+
+      /**
+       * Where the request appeared to come from, as an ISO 3166-1 alpha-2 code. Named
+       * separately from the country on a channel event, which is a destination market
+       * the customer registered for — this one is a property of a single visitor and is
+       * absent when the edge could not resolve it.
+       */
+      access_country?: string | null;
+
+      /**
+       * How the request was served, when the edge recorded it. Free text describing the
+       * outcome — show it to a human rather than branching on it.
+       */
+      access_outcome?: string | null;
+
+      /**
+       * The requesting browser family, for example chrome or safari, or unknown. Derived
+       * from the user agent.
+       */
+      browser?: string | null;
+
+      /**
+       * How many bytes were served, for a file access. A ranged request reports the
+       * bytes in that range, not the size of the file, so several accesses of one file
+       * can each report a part.
+       */
+      bytes_served?: number | null;
+
+      /**
+       * The channel the message carrying this link went out on: sms, whatsapp, or rcs.
+       */
+      channel?: string | null;
+
+      /**
+       * The organization the link belongs to. Always the parent account, never a sender
+       * profile — read SenderProfileId for that.
+       *
+       * This family publishes the owner as an explicit pair rather than the single
+       * account_id the other families use. The pair says which organization and which
+       * profile without the subscriber deriving either, which is the trade: one more key
+       * against not having to know that account_id silently becomes the profile when one
+       * exists.
+       */
+      customer_id?: string;
+
+      /**
+       * The requesting device class: mobile, tablet, desktop or unknown. Derived from
+       * the user agent.
+       */
+      device?: string | null;
+
+      /**
+       * What the link points at: url for a destination the customer supplied, file for
+       * media Sent hosts. Always present, and implied by the event — link.clicked is
+       * always url and link.downloaded always file — but published as its own field so a
+       * subscriber can branch on the kind without parsing the event name, the same
+       * separation the channel family keeps between its event and its status.
+       */
+      link_kind?: string;
+
+      /**
+       * The message the link was published in.
+       *
+       * The event can arrive before the message is readable through GET /v3/messages: a
+       * provider may fetch a link within milliseconds of the send, and nothing here
+       * waits for the message row. Retry the read rather than treating an unknown id as
+       * an error.
+       */
+      message_id?: string | null;
+
+      /**
+       * When the access or lifecycle change actually happened, in UTC
+       * (yyyy-MM-ddTHH:mm:ssZ). The envelope's timestamp is when Sent emitted the event;
+       * this is when the thing occurred, and the two differ by the ingest delay.
+       */
+      occurred_at?: string;
+
+      /**
+       * The caller-supplied label tying this link back to a position in the message, for
+       * example body:0 for the first link in the body. Present when the link was created
+       * with one.
+       */
+      reference_key?: string | null;
+
+      /**
+       * The host of the page that linked here, when the request supplied one. The host
+       * only — never a full referring URL.
+       */
+      referrer_host?: string | null;
+
+      /**
+       * The HTTP method of the request that was served, for an access event. Omitted on
+       * link.expired and link.revoked, which describe no request.
+       */
+      request_method?: string | null;
+
+      /**
+       * The sender profile that owns the link, or null when the organization owns it
+       * directly. Always on the wire so a handler reads one shape rather than branching
+       * on whether the key arrived.
+       *
+       * sender_profile_id, not profile_id: the API already publishes
+       * messaging_profile_id and sending_phone_number_profile_id for provider-side
+       * profiles, which are a different thing entirely. The unqualified name would read
+       * as one of those.
+       */
+      sender_profile_id?: string | null;
+
+      /**
+       * The HTTP status Sent answered the request with: 302 for a link, 200 or 206 for a
+       * file. Omitted on lifecycle events.
+       */
+      status_code?: number | null;
+
+      /**
+       * A coarse guess at what made the request: likely_human, provider (a messaging
+       * platform prefetching the link), bot, or unknown. Derived from the user agent, so
+       * it is a hint for filtering noise rather than a fact to bill or report on.
+       */
+      traffic_class?: string | null;
+    }
+  }
+}
+
 /**
  * Standard API response envelope for all v3 endpoints
  */
@@ -1110,6 +1848,10 @@ export declare namespace Webhooks {
   export {
     type APIMeta as APIMeta,
     type APIResponseWebhook as APIResponseWebhook,
+    type ChannelEvent as ChannelEvent,
+    type ChannelEventPayload as ChannelEventPayload,
+    type ContactEvent as ContactEvent,
+    type ContactEventPayload as ContactEventPayload,
     type ErrorDetail as ErrorDetail,
     type InboundMessageEvent as InboundMessageEvent,
     type InboundMessageEventPayload as InboundMessageEventPayload,