Interface OpenApiWebhooks

Type declaration

• Optionaldelete?: undefined

• Optionalget?: undefined

• Optionalhead?: undefined

• Optionaloptions?: undefined

• parameters: { cookie?: undefined; header?: undefined; path?: undefined; query?: undefined }

• Optionalpatch?: undefined

• post: {
      parameters: {
          cookie?: undefined;
          header?: undefined;
          path?: undefined;
          query?: undefined;
      };
      requestBody: {
          content: {
              "application/json": (
                  | {
                      credits_spent: number;
                      error?: { code: number; message: string };
                      field: "ai_plan_generated" | "ai_plan_failed";
                      id_ai_plan: string;
                      id_organization: string;
                      state: "generated" | "failed";
                      template:
                          | "standard"
                          | "from_images"
                          | "from_text"
                          | "from_catalog"
                          | "campaign";
                      total_publications: number;
                      warnings: number;
                  }
                  | {
                      error_code: number;
                      field: "integration_error";
                      id_integration: string;
                      id_organization: string;
                      provider: string;
                  }
                  | {
                      commentObj?: {
                          _id: string;
                          author: {
                              external_id: string;
                              is_own: boolean;
                              name?: (...)
                              | (...);
                              profile_pic?: (...) | (...);
                          };
                          collected_date: string;
                          creation_date: string;
                          deleted: boolean;
                          external_id: string;
                          hidden: boolean;
                          id_account: | string
                          | {
                              _id: ...;
                              creation_date: ...;
                              error_code: ...;
                              extra_data?: ...;
                              followers_count?: ...;
                              id_client: ...;
                              id_organization: ...;
                              image?: ...;
                              name: ...;
                              next_comments_update?: ...;
                              next_stats_update?: ...;
                              private_message_link?: ...;
                              social_network: ...;
                              username?: ...;
                          };
                          id_organization: string;
                          id_publication?: | string
                          | {
                              _id: ...;
                              ai_generated?: ...;
                              creation_date: ...;
                              destination?: ...;
                              engagement_base?: ...;
                              external_identifier?: ...;
                              extra_data?: ...;
                              files: ...;
                              id_account: ...;
                              id_integration?: ...;
                              id_organization: ...;
                              link?: ...;
                              made_for_kids?: ...;
                              metrics?: ...;
                              name?: ...;
                              next_stats_update?: ...;
                              pending_publish?: ...;
                              publication_errors: ...;
                              publication_type: ...;
                              publication_warnings?: ...;
                              publish_date?: ...;
                              reply_control?: ...;
                              retries: ...;
                              social_network: ...;
                              state: ...;
                              statistics?: ...;
                              stats_updated_date?: ...;
                              text?: ...;
                              title?: ...;
                              url?: ...;
                              visibility?: ...;
                          };
                          like_count?: number;
                          our_reply_external_id?: string;
                          parent_external_id?: string;
                          publication_external_id: string;
                          rating?: number;
                          read: boolean;
                          replied: boolean;
                          reply_count?: number;
                          social_network: | "facebook"
                          | "instagram"
                          | "linkedin"
                          | "twitter"
                          | "youtube"
                          | "google_business"
                          | "bluesky"
                          | "discord"
                          | "telegram"
                          | "threads";
                          text: string;
                      };
                      field: | "comments"
                      | "messages"
                      | "new_account"
                      | "change_state_account"
                      | "messaging_postbacks"
                      | "messaging_seen"
                      | "messaging_error";
                      id_account: string;
                      id_contact?: string;
                      id_organization: string;
                      messageObj?: {
                          _id: string;
                          contact_id?: | string
                          | {
                              _id: ...;
                              creation_date: ...;
                              creator_keycloak_identifier?: ...;
                              extra_data?: ...;
                              id_organization: ...;
                              last_contact_update: ...;
                              name?: ...;
                              profile_image?: ...;
                              social_identifiers: ...;
                          };
                          creation_date: string;
                          element_external_id?: string;
                          from_contact_id?: | string
                          | {
                              _id: ...;
                              creation_date: ...;
                              creator_keycloak_identifier?: ...;
                              extra_data?: ...;
                              id_organization: ...;
                              last_contact_update: ...;
                              name?: ...;
                              profile_image?: ...;
                              social_identifiers: ...;
                          };
                          id_account: string;
                          in_response_external_id?: string;
                          in_response_to?: string;
                          message_errors: { code: ...; data?: ...; message: ... }[];
                          message_options: {
                              files: (...)[];
                              files_urls: (...)[];
                              metaElements?: (...) | (...);
                              metaQuickReplies?: (...) | (...);
                              payload?: (...) | (...);
                              template_language?: (...) | (...);
                              template_name?: (...) | (...);
                              template_parameters?: (...) | (...);
                              whatsappInteractive?: (...) | (...);
                          };
                          message_type: | "simple_message"
                          | "file_message"
                          | "comment_message"
                          | "publication_message"
                          | "quick_reply_message"
                          | "button_message"
                          | "elements_message"
                          | "postback_message"
                          | "template_message"
                          | "interactive_message";
                          read: boolean;
                          text?: string;
                      };
                      originalChange?: { [key: string]: unknown };
                      social_network:
                          | "facebook"
                          | "instagram"
                          | "linkedin"
                          | "tiktok"
                          | "twitter"
                          | "whatsapp"
                          | "youtube"
                          | "google_business"
                          | "bluesky"
                          | "discord"
                          | "telegram"
                          | "threads"
                          | "slack"
                          | "pinterest";
                  }
              )[];
          };
      };
      responses: {
          "200": { content?: undefined; headers: { [name: string]: unknown } };
      };
  }

  A change happened (notification to your app)

  Description

  PlanVortex POSTs to the webhook_url of your client app when something happens. The body is an array of changes, and each one carries field telling you what it is — switch on it and ignore what you do not handle, because the list grows with the product.

  Three shapes travel in that array. A change on an **account** (`WebhookChange`) always carries `id_account`, `id_organization` and `social_network`. A change on an **integration** (`IntegrationWebhookChange`) and the end of an **AI plan** (`AiPlanWebhookChange`) carry none of those, because they hang off the organization and not off any account.
  
  The events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments`, `integration_error`, `ai_plan_generated` and `ai_plan_failed`.
  
  ### Comments
  
  `field: "comments"` is the one for this section, and the comment itself travels in **`commentObj`** — a property of its own, never in `messageObj`. That is deliberate: a comment is not a message, it has no contact and it hangs off a publication. A consumer that only understands messages sees `commentObj` as absent and ignores the change, which is exactly what should happen.
  
  **Which networks arrive this way:** Facebook and Instagram, because Meta pushes them. YouTube, LinkedIn and Google Business have no comment webhook, so those are polled by a background job and appear in the inbox within a few hours rather than instantly. X is polled too, and only when the organization turns it on, because reading replies there is billed per unit.
  
  **Meta repeats deliveries.** The same comment can arrive more than once; the backend is idempotent about it and so should you be — deduplicate on `commentObj.external_id`.
  
  ### AI plans
  
  `ai_plan_generated` and `ai_plan_failed` say that a plan has **finished**: it was generated, or it gave up. Instead of polling the plan every few seconds, wait for one of these and then read it once with `GET /clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}`. The change carries ids and numbers only, never the prompt or the generated text, so the publications are in that `GET`.
  
  A plan that hits a transient error goes back to the queue and is retried. That is not an end and sends nothing, so each plan sends **one** of these two events, never a `failed` followed by a `generated`. A plan generated with notices (`warnings` above zero) is still `ai_plan_generated`: it is usable, and the notices are in the plan.
  
  The event goes to **every** app of the client that has a `webhook_url`, not only to the one that created the plan. And it is not retried: if your endpoint was down when the plan finished, the `GET` still tells you how it ended, so on startup read the plans you were waiting for.
  
  ### Verifying the signature
  
  Every delivery carries the body signed with your app's secret, twice:
  
  - `x-hub-signature`: `sha1=<hmac>`
  - `x-hub-signature-256`: `sha256=<hmac>`
  
  Compute the HMAC over the **raw** request body — not over a re-serialized copy of the parsed JSON — and compare in constant time. Prefer the sha256 header.
  
  Delivery is best effort: PlanVortex does not retry a webhook that fails.
  

  • parameters: { cookie?: undefined; header?: undefined; path?: undefined; query?: undefined }

  • requestBody: {
        content: {
            "application/json": (
                | {
                    credits_spent: number;
                    error?: { code: number; message: string };
                    field: "ai_plan_generated" | "ai_plan_failed";
                    id_ai_plan: string;
                    id_organization: string;
                    state: "generated" | "failed";
                    template:
                        | "standard"
                        | "from_images"
                        | "from_text"
                        | "from_catalog"
                        | "campaign";
                    total_publications: number;
                    warnings: number;
                }
                | {
                    error_code: number;
                    field: "integration_error";
                    id_integration: string;
                    id_organization: string;
                    provider: string;
                }
                | {
                    commentObj?: {
                        _id: string;
                        author: {
                            external_id: string;
                            is_own: boolean;
                            name?: (...)
                            | (...);
                            profile_pic?: (...) | (...);
                        };
                        collected_date: string;
                        creation_date: string;
                        deleted: boolean;
                        external_id: string;
                        hidden: boolean;
                        id_account: | string
                        | {
                            _id: ...;
                            creation_date: ...;
                            error_code: ...;
                            extra_data?: ...;
                            followers_count?: ...;
                            id_client: ...;
                            id_organization: ...;
                            image?: ...;
                            name: ...;
                            next_comments_update?: ...;
                            next_stats_update?: ...;
                            private_message_link?: ...;
                            social_network: ...;
                            username?: ...;
                        };
                        id_organization: string;
                        id_publication?: | string
                        | {
                            _id: ...;
                            ai_generated?: ...;
                            creation_date: ...;
                            destination?: ...;
                            engagement_base?: ...;
                            external_identifier?: ...;
                            extra_data?: ...;
                            files: ...;
                            id_account: ...;
                            id_integration?: ...;
                            id_organization: ...;
                            link?: ...;
                            made_for_kids?: ...;
                            metrics?: ...;
                            name?: ...;
                            next_stats_update?: ...;
                            pending_publish?: ...;
                            publication_errors: ...;
                            publication_type: ...;
                            publication_warnings?: ...;
                            publish_date?: ...;
                            reply_control?: ...;
                            retries: ...;
                            social_network: ...;
                            state: ...;
                            statistics?: ...;
                            stats_updated_date?: ...;
                            text?: ...;
                            title?: ...;
                            url?: ...;
                            visibility?: ...;
                        };
                        like_count?: number;
                        our_reply_external_id?: string;
                        parent_external_id?: string;
                        publication_external_id: string;
                        rating?: number;
                        read: boolean;
                        replied: boolean;
                        reply_count?: number;
                        social_network: | "facebook"
                        | "instagram"
                        | "linkedin"
                        | "twitter"
                        | "youtube"
                        | "google_business"
                        | "bluesky"
                        | "discord"
                        | "telegram"
                        | "threads";
                        text: string;
                    };
                    field: | "comments"
                    | "messages"
                    | "new_account"
                    | "change_state_account"
                    | "messaging_postbacks"
                    | "messaging_seen"
                    | "messaging_error";
                    id_account: string;
                    id_contact?: string;
                    id_organization: string;
                    messageObj?: {
                        _id: string;
                        contact_id?: | string
                        | {
                            _id: ...;
                            creation_date: ...;
                            creator_keycloak_identifier?: ...;
                            extra_data?: ...;
                            id_organization: ...;
                            last_contact_update: ...;
                            name?: ...;
                            profile_image?: ...;
                            social_identifiers: ...;
                        };
                        creation_date: string;
                        element_external_id?: string;
                        from_contact_id?: | string
                        | {
                            _id: ...;
                            creation_date: ...;
                            creator_keycloak_identifier?: ...;
                            extra_data?: ...;
                            id_organization: ...;
                            last_contact_update: ...;
                            name?: ...;
                            profile_image?: ...;
                            social_identifiers: ...;
                        };
                        id_account: string;
                        in_response_external_id?: string;
                        in_response_to?: string;
                        message_errors: { code: ...; data?: ...; message: ... }[];
                        message_options: {
                            files: (...)[];
                            files_urls: (...)[];
                            metaElements?: (...) | (...);
                            metaQuickReplies?: (...) | (...);
                            payload?: (...) | (...);
                            template_language?: (...) | (...);
                            template_name?: (...) | (...);
                            template_parameters?: (...) | (...);
                            whatsappInteractive?: (...) | (...);
                        };
                        message_type: | "simple_message"
                        | "file_message"
                        | "comment_message"
                        | "publication_message"
                        | "quick_reply_message"
                        | "button_message"
                        | "elements_message"
                        | "postback_message"
                        | "template_message"
                        | "interactive_message";
                        read: boolean;
                        text?: string;
                    };
                    originalChange?: { [key: string]: unknown };
                    social_network:
                        | "facebook"
                        | "instagram"
                        | "linkedin"
                        | "tiktok"
                        | "twitter"
                        | "whatsapp"
                        | "youtube"
                        | "google_business"
                        | "bluesky"
                        | "discord"
                        | "telegram"
                        | "threads"
                        | "slack"
                        | "pinterest";
                }
            )[];
        };
    }

    • content: {
          "application/json": (
              | {
                  credits_spent: number;
                  error?: { code: number; message: string };
                  field: "ai_plan_generated" | "ai_plan_failed";
                  id_ai_plan: string;
                  id_organization: string;
                  state: "generated" | "failed";
                  template:
                      | "standard"
                      | "from_images"
                      | "from_text"
                      | "from_catalog"
                      | "campaign";
                  total_publications: number;
                  warnings: number;
              }
              | {
                  error_code: number;
                  field: "integration_error";
                  id_integration: string;
                  id_organization: string;
                  provider: string;
              }
              | {
                  commentObj?: {
                      _id: string;
                      author: {
                          external_id: string;
                          is_own: boolean;
                          name?: (...)
                          | (...);
                          profile_pic?: (...) | (...);
                      };
                      collected_date: string;
                      creation_date: string;
                      deleted: boolean;
                      external_id: string;
                      hidden: boolean;
                      id_account: | string
                      | {
                          _id: ...;
                          creation_date: ...;
                          error_code: ...;
                          extra_data?: ...;
                          followers_count?: ...;
                          id_client: ...;
                          id_organization: ...;
                          image?: ...;
                          name: ...;
                          next_comments_update?: ...;
                          next_stats_update?: ...;
                          private_message_link?: ...;
                          social_network: ...;
                          username?: ...;
                      };
                      id_organization: string;
                      id_publication?: | string
                      | {
                          _id: ...;
                          ai_generated?: ...;
                          creation_date: ...;
                          destination?: ...;
                          engagement_base?: ...;
                          external_identifier?: ...;
                          extra_data?: ...;
                          files: ...;
                          id_account: ...;
                          id_integration?: ...;
                          id_organization: ...;
                          link?: ...;
                          made_for_kids?: ...;
                          metrics?: ...;
                          name?: ...;
                          next_stats_update?: ...;
                          pending_publish?: ...;
                          publication_errors: ...;
                          publication_type: ...;
                          publication_warnings?: ...;
                          publish_date?: ...;
                          reply_control?: ...;
                          retries: ...;
                          social_network: ...;
                          state: ...;
                          statistics?: ...;
                          stats_updated_date?: ...;
                          text?: ...;
                          title?: ...;
                          url?: ...;
                          visibility?: ...;
                      };
                      like_count?: number;
                      our_reply_external_id?: string;
                      parent_external_id?: string;
                      publication_external_id: string;
                      rating?: number;
                      read: boolean;
                      replied: boolean;
                      reply_count?: number;
                      social_network: | "facebook"
                      | "instagram"
                      | "linkedin"
                      | "twitter"
                      | "youtube"
                      | "google_business"
                      | "bluesky"
                      | "discord"
                      | "telegram"
                      | "threads";
                      text: string;
                  };
                  field: | "comments"
                  | "messages"
                  | "new_account"
                  | "change_state_account"
                  | "messaging_postbacks"
                  | "messaging_seen"
                  | "messaging_error";
                  id_account: string;
                  id_contact?: string;
                  id_organization: string;
                  messageObj?: {
                      _id: string;
                      contact_id?: | string
                      | {
                          _id: ...;
                          creation_date: ...;
                          creator_keycloak_identifier?: ...;
                          extra_data?: ...;
                          id_organization: ...;
                          last_contact_update: ...;
                          name?: ...;
                          profile_image?: ...;
                          social_identifiers: ...;
                      };
                      creation_date: string;
                      element_external_id?: string;
                      from_contact_id?: | string
                      | {
                          _id: ...;
                          creation_date: ...;
                          creator_keycloak_identifier?: ...;
                          extra_data?: ...;
                          id_organization: ...;
                          last_contact_update: ...;
                          name?: ...;
                          profile_image?: ...;
                          social_identifiers: ...;
                      };
                      id_account: string;
                      in_response_external_id?: string;
                      in_response_to?: string;
                      message_errors: { code: ...; data?: ...; message: ... }[];
                      message_options: {
                          files: (...)[];
                          files_urls: (...)[];
                          metaElements?: (...) | (...);
                          metaQuickReplies?: (...) | (...);
                          payload?: (...) | (...);
                          template_language?: (...) | (...);
                          template_name?: (...) | (...);
                          template_parameters?: (...) | (...);
                          whatsappInteractive?: (...) | (...);
                      };
                      message_type: | "simple_message"
                      | "file_message"
                      | "comment_message"
                      | "publication_message"
                      | "quick_reply_message"
                      | "button_message"
                      | "elements_message"
                      | "postback_message"
                      | "template_message"
                      | "interactive_message";
                      read: boolean;
                      text?: string;
                  };
                  originalChange?: { [key: string]: unknown };
                  social_network:
                      | "facebook"
                      | "instagram"
                      | "linkedin"
                      | "tiktok"
                      | "twitter"
                      | "whatsapp"
                      | "youtube"
                      | "google_business"
                      | "bluesky"
                      | "discord"
                      | "telegram"
                      | "threads"
                      | "slack"
                      | "pinterest";
              }
          )[];
      }

      • application/json: (
            | {
                credits_spent: number;
                error?: { code: number; message: string };
                field: "ai_plan_generated" | "ai_plan_failed";
                id_ai_plan: string;
                id_organization: string;
                state: "generated" | "failed";
                template:
                    | "standard"
                    | "from_images"
                    | "from_text"
                    | "from_catalog"
                    | "campaign";
                total_publications: number;
                warnings: number;
            }
            | {
                error_code: number;
                field: "integration_error";
                id_integration: string;
                id_organization: string;
                provider: string;
            }
            | {
                commentObj?: {
                    _id: string;
                    author: {
                        external_id: string;
                        is_own: boolean;
                        name?: (...)
                        | (...);
                        profile_pic?: (...) | (...);
                    };
                    collected_date: string;
                    creation_date: string;
                    deleted: boolean;
                    external_id: string;
                    hidden: boolean;
                    id_account: | string
                    | {
                        _id: ...;
                        creation_date: ...;
                        error_code: ...;
                        extra_data?: ...;
                        followers_count?: ...;
                        id_client: ...;
                        id_organization: ...;
                        image?: ...;
                        name: ...;
                        next_comments_update?: ...;
                        next_stats_update?: ...;
                        private_message_link?: ...;
                        social_network: ...;
                        username?: ...;
                    };
                    id_organization: string;
                    id_publication?: | string
                    | {
                        _id: ...;
                        ai_generated?: ...;
                        creation_date: ...;
                        destination?: ...;
                        engagement_base?: ...;
                        external_identifier?: ...;
                        extra_data?: ...;
                        files: ...;
                        id_account: ...;
                        id_integration?: ...;
                        id_organization: ...;
                        link?: ...;
                        made_for_kids?: ...;
                        metrics?: ...;
                        name?: ...;
                        next_stats_update?: ...;
                        pending_publish?: ...;
                        publication_errors: ...;
                        publication_type: ...;
                        publication_warnings?: ...;
                        publish_date?: ...;
                        reply_control?: ...;
                        retries: ...;
                        social_network: ...;
                        state: ...;
                        statistics?: ...;
                        stats_updated_date?: ...;
                        text?: ...;
                        title?: ...;
                        url?: ...;
                        visibility?: ...;
                    };
                    like_count?: number;
                    our_reply_external_id?: string;
                    parent_external_id?: string;
                    publication_external_id: string;
                    rating?: number;
                    read: boolean;
                    replied: boolean;
                    reply_count?: number;
                    social_network: | "facebook"
                    | "instagram"
                    | "linkedin"
                    | "twitter"
                    | "youtube"
                    | "google_business"
                    | "bluesky"
                    | "discord"
                    | "telegram"
                    | "threads";
                    text: string;
                };
                field: | "comments"
                | "messages"
                | "new_account"
                | "change_state_account"
                | "messaging_postbacks"
                | "messaging_seen"
                | "messaging_error";
                id_account: string;
                id_contact?: string;
                id_organization: string;
                messageObj?: {
                    _id: string;
                    contact_id?: | string
                    | {
                        _id: ...;
                        creation_date: ...;
                        creator_keycloak_identifier?: ...;
                        extra_data?: ...;
                        id_organization: ...;
                        last_contact_update: ...;
                        name?: ...;
                        profile_image?: ...;
                        social_identifiers: ...;
                    };
                    creation_date: string;
                    element_external_id?: string;
                    from_contact_id?: | string
                    | {
                        _id: ...;
                        creation_date: ...;
                        creator_keycloak_identifier?: ...;
                        extra_data?: ...;
                        id_organization: ...;
                        last_contact_update: ...;
                        name?: ...;
                        profile_image?: ...;
                        social_identifiers: ...;
                    };
                    id_account: string;
                    in_response_external_id?: string;
                    in_response_to?: string;
                    message_errors: { code: ...; data?: ...; message: ... }[];
                    message_options: {
                        files: (...)[];
                        files_urls: (...)[];
                        metaElements?: (...) | (...);
                        metaQuickReplies?: (...) | (...);
                        payload?: (...) | (...);
                        template_language?: (...) | (...);
                        template_name?: (...) | (...);
                        template_parameters?: (...) | (...);
                        whatsappInteractive?: (...) | (...);
                    };
                    message_type: | "simple_message"
                    | "file_message"
                    | "comment_message"
                    | "publication_message"
                    | "quick_reply_message"
                    | "button_message"
                    | "elements_message"
                    | "postback_message"
                    | "template_message"
                    | "interactive_message";
                    read: boolean;
                    text?: string;
                };
                originalChange?: { [key: string]: unknown };
                social_network:
                    | "facebook"
                    | "instagram"
                    | "linkedin"
                    | "tiktok"
                    | "twitter"
                    | "whatsapp"
                    | "youtube"
                    | "google_business"
                    | "bluesky"
                    | "discord"
                    | "telegram"
                    | "threads"
                    | "slack"
                    | "pinterest";
            }
        )[]

        Example

        [
              {
                "field": "comments",
                "id_account": "66b0f4a1c2d3e4f5a6b7c8d9",
                "id_organization": "66b0f4a1c2d3e4f5a6b7c8d0",
                "social_network": "instagram",
                "commentObj": {
                  "_id": "66c1a2b3c4d5e6f7a8b9c0d1",
                  "id_account": "66b0f4a1c2d3e4f5a6b7c8d9",
                  "id_organization": "66b0f4a1c2d3e4f5a6b7c8d0",
                  "publication_external_id": "17900000000000000",
                  "external_id": "17800000000000001",
                  "social_network": "instagram",
                  "author": {
                    "external_id": "9988776655",
                    "name": "un_seguidor",
                    "is_own": false
                  },
                  "text": "Me interesa, ¿cuánto cuesta?",
                  "creation_date": "2026-08-19T09:12:00.000Z",
                  "collected_date": "2026-08-19T09:12:01.000Z",
                  "read": false,
                  "replied": false,
                  "hidden": false,
                  "deleted": false
                }
              }
            ]
        Copy

  • responses: { "200": { content?: undefined; headers: { [name: string]: unknown } } }

    • 200: { content?: undefined; headers: { [name: string]: unknown } }

      Description

      Your endpoint acknowledged the delivery. PlanVortex does not retry: a delivery that fails is logged and dropped, so treat the inbox endpoints as the way to catch up on anything you missed.

• Optionalput?: undefined

• Optionaltrace?: undefined