GuideReference
magicplan Cloud

Webhook Documentation: Project Updated

The Project Updated webhook is triggered when a user generates new files or updates an existing project via the Custom Export Button in magicplan. While implementing this webhook is not mandatory, it is highly recommended for seamless integration and immediate file processing.

If no webhook URL is specified by the client:

  • magicplan assigns a default URL that performs no action.

  • The files generated during export can only be accessed through the Project Files API, instead of being included in the webhook request.

By providing a valid webhook URL, you can receive the exported files and project details directly, simplifying the process.

🔹 How to Set Up Your Webhook

To configure your webhook, make a PUT request to the Workspace API and set the webhook_url field.

Webhook Encoding

To ensure worldwide interoperability, the strings and file URLs in the request are encoded as follows:

  1. The character string is converted into a sequence of bytes using UTF-8 encoding.

  2. Each byte that is not an ASCII letter or digit is converted to %HH, where HH is the hexadecimal value of the byte (e.g., électrique becomes %C3%A9lectrique).

Sequence of Events

This webhook is part of a sequence used to notify your application about updates to floor plans:

  1. Create and Link Project:
    The project is created and linked in one step by specifying the external_reference_id. This field represents the identifier of your local project that is assigned to the magicplan project.

  2. Authorize Export (Optional):
    If configured, the project is authorized for export.

  3. Floor Plan Updated (Webhook Trigger):
    When updates are made to the floor plan, magicplan sends the webhook request to your endpoint with updated files and metadata. If no webhook URL is specified, the files must be accessed through the Project Files API.

HTTP RequestCopied!

  • Method: POST

  • Endpoint: https://yourserverurl/update

  • The webhook includes file URLs (valid for 60 minutes) and relevant metadata about the project.

Request SchemaCopied!

Parameter

Required

Description

key

Yes

The magicplan API key provided by magicplan.

email

Yes

The user's email address.

title

Yes

A human-readable title of the project being updated.

planid

Yes

The unique identifier of the plan being updated.

project_id

Yes

The unique identifier of the project being updated.

listing

No

The ID of your local project linked to the magicplan project. This is referenced as external_reference_id in the Workspace API

pdf

No

The URL of the updated PDF file.

jpg0, jpg1

No

URLs of JPG files, one per floor (e.g., jpg0 for floor 0).

dxf0, dxf1

No

URLs of DXF files, one per floor.

png0, png1

No

URLs of PNG files, one per floor.

svg0, svg1

No

URLs of SVG files, one per floor.

xml

No

The URL of the updated magicplan file in XML format.

html

No

The URL of the updated web file.

ifc

No

The URL of the IFC file for the entire project.

usdz

No

The URL of the USDZ file for the entire project.

obj

No

The URL of the OBJ file for the entire project.

Response SchemaCopied!

XML Tag

Value

Description

<status>

0

The request was a success.

1

The API key is invalid.

14

The given user reference or email does not exist.

18

The given listing does not exist.

<message>

Optional

A message that will be displayed in the magicplan app, providing feedback to the user.

XML SchemaCopied! 

<xs:element name="MagicPlanService">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="status">
        <xs:simpleType>
          <xs:restriction base="xs:integer">
            <xs:enumeration value="0"/>
            <xs:enumeration value="1"/>
            <xs:enumeration value="14"/>
            <xs:enumeration value="18"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="message" type="xs:string" minOccurs="0">
        <xs:annotation>
          <xs:documentation>
            An optional message that will be displayed to the user in the magicplan app.
          </xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>

Example Webhook RequestCopied! 

POST /update HTTP/1.1
Host: yourserverurl
Content-Type: application/x-www-form-urlencoded

key=3b2abe7cd80d&
email=john.doe%40example.com&
project_id=73377c22-0366-4f1c-9308-8d1c2fbb05d0&
planid=c32ea8d1-fee3-4c81-b402-eb3f85772cf8&
title=Plan+3&
pdf=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.pdf&
jpg0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.jpg&
dxf0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.dxf&
png0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.png&
svg0=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.svg&
xml=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.xml&
html=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.html&
embedded=https%3A%2F%2Fs3.amazonaws.com%2Fprod.plans.sensopia.com%2Fc32ea8d1-fee3-4c81-b402-eb3f85772cf8%2Fac2abe7cd8d0%2FPlan%203.embedded.html
Previous Page

Custom Export Button Integration

Next Page

Authorize export from magicplan