Add a Webhook Integration to Punchlist

Good news! Punchlist now has webhook integration capabilities so you can connect your favorite applications and make feedback management even easier. With Punchlist webhooks, you can:

• Set up your own custom integrations and workflows with ease
• Boost your team's productivity by integrating Punchlist into your workflow
• Get notified on other platforms automatically when changes are made in Punchlist

What Are Webhooks?

Webhooks are automated messages sent from one app to another when a specific event occurs. They’re a way for your apps to talk to each other and share information automatically.

For instance, when something happens in Punchlist—like a new project being created or an item’s status changing—a webhook can automatically notify another application you use, triggering an action or updating information.

How Do Webhooks Work?

Webhooks work by connecting two systems. When an event occurs in the first system, a payload is sent via an HTTP POST to the other application’s webhook endpoint. This request contains a payload holding important information about the event that triggered the request such as project details, user information, and item metadata.

The tool at the other end of the event processes the incoming data. This could be another project management tool, a CRM, an analytics platform, or any other application that supports webhooks. Here are the actions you can take in Punchlist that trigger a webhook:

• Project created
• Project updated
• Project archived
• Feedback item created
• Feedback item updated
• Feedback item deleted

How Do You Use a Webhook?

You use a webhook by connecting Punchlist to a webhook endpoint. An endpoint is a specific, public URL that belongs to the receiving system. 

Once they’re connected, you’ll receive payloads in the endpoint system whenever an event is triggered in the requesting system.

How to Create a Webhook

1. Go to your Punchlist workspace settings > Developers > Add a Webhook
   
2. Enter the URL of the endpoint
3. Click Add
4. The webhook will populate under the section Manage Webhooks 

Now any time an event is triggered in Punchlist, the webhook endpoint will receive the appropriate payload.

Note: Each user will only have access to two active webhooks at a time. 

Request and Payload

Whenever an action triggers the webhook, a POST request with a JSON payload will be sent by Punchlist to the endpoint you added. Here are the triggerable actions and examples of the payload:

Project Created

    {
      "event": "project.created",
      "data": {
        "id": "505e30ce-6cdc-4cf9-9ee8-4388ce1f4bbe",
        "name": "Figma Demo 3",
        "url": "https://app.punchlist.com/projects/zULCFDjLBgWc2lx9",
        "thumbnail_url": null,
        "type": "figma",
        "owner": {
          "name": "Nic",
          "email": "nic@punchlist.com"
        }
      }
    }
    

‍

Project Updated

{
  "event": "project.updated",
  "data": {
    "id": "505e30ce-6cdc-4cf9-9ee8-4388ce1f4bbe",
    "name": "Figma Demo 3",
    "url": "https://app.punchlist.com/projects/zULCFDjLBgWc2lx9",
    "thumbnail_url": "https://cdn.filestackcontent.com/security=policy:
    eyJleHBpcnkiOjIwMzE2NTY0MDcsImNhbGwiOlsicGljayIsInJlYWQiLCJzdG9yZSIsImNvbnZlcnQiLCJyZW1vdmUiXX0=,
    signature:6393a4fca0be3e527bbec92f48697bf115112ed38ff1ae456e648f05400c110b/
    resize=w:720,h:450,f:crop,a:top/7YBKHBSqTqGAHuUxMVyo",
    "type": "figma",
    "owner": {
      "name": "Nic",
      "email": "nic@punchlist.com"
    }
  }
}

‍

Project Archived

{
  "event": "project.archived",
  "data": {
    "id": "6f03d6fb-bf61-4599-833d-2bc69cf38939"
  }
}
    

‍

Feedback Item Created

{
  "event": "item.created",
  "data": {
    "url": "https://app.punchlist.com/items/8c6b5db2-3f99-45ac-af55-ba8ca37a88a6/show",
    "owner": {
      "name": "Mo Punch",
      "email": "worth.mcfall@punchlist.com",
      "is_team_member": false
    },
    "project": {
      "name": "Figma Demo 3",
      "url": "https://app.punchlist.com/projects/zULCFDjLBgWc2lx9"
    },
    "content": {
      "html": "
Change copy to:

\"Get a Demo\" 
",
      "text": "Change copy to:\"Get a Demo\" "
    },
    "screenshot_url": null,
    "meta": {
      "browser": "Chrome",
      "os": "macOS Catalina 10.15",
      "browser_version": "124.0.0.0",
      "breakpoint": "Full Width - 100%",
      "screen_width": 1052,
      "screen_height": 615
    },
    "status": "Open",
    "position": {
      "x": 0.191739,
      "y": 0.105068
    },
    "assignee": null,
    "team_only": false,
    "id": "8c6b5db2-3f99-45ac-af55-ba8ca37a88a6"
  }
}

    

‍

Feedback Item Updated

{
  "event": "item.updated",
  "data": {
    "url": "https://app.punchlist.com/items/8c6b5db2-3f99-45ac-af55-ba8ca37a88a6/show",
    "owner": {
      "name": "Mo Punch",
      "email": "worth.mcfall@punchlist.com",
      "is_team_member": false
    },
    "project": {
      "name": "Figma Demo 3",
      "url": "https://app.punchlist.com/projects/zULCFDjLBgWc2lx9"
    },
    "content": {
      "html": "
Change copy to:

\"Get a Demo\" 
",
      "text": "Change copy to:\"Get a Demo\" "
    },
    "screenshot_url": "https://cdn.filestackcontent.com/security=policy:
    eyJleHBpcnkiOjIwMzE2NTkzNzQsImNhbGwiOlsicGljay
    IsInJlYWQiLCJzdG9yZSIsImNvbnZlcnQiLCJyZW1vdmUiXX0=,
    signature:dbead000b31bef436bfa311b46d6db3a0f19d13a
    bf671a000a3ee91163d66d79/resize=w:720,
    h:450,f:crop,a:center/1yylLykGRBKHtsIzHm0E",
    "meta": {
      "browser": "Chrome",
      "os": "macOS Catalina 10.15",
      "browser_version": "124.0.0.0",
      "breakpoint": "Full Width - 100%",
      "screen_width": 1052,
      "screen_height": 615
    },
    "status": "In Progress",
    "position": {
      "x": 0.191739,
      "y": 0.105068
    },
    "assignee": null,
    "team_only": false,
    "id": "8c6b5db2-3f99-45ac-af55-ba8ca37a88a6"
  }
}
    

‍

Feedback Item Deleted

{
  "event": "item.deleted",
  "data": {
    "id": "096d0375-b0db-4196-b483-53aab3d3bc83"
  }
}
    

‍

Test if Your Webhook Integration Works

To ensure the functionality of your webhook, here’s what you can do

• Go to an existing or new project
• Complete one of the specified items in the How Do Webhooks Work? or Requests and Payload section of this article
• You should immediately start seeing the payloads hit your webhook
• If it fails more than three times, the status of your webhook will change to Failed and no more attempts will be made

If you need help setting up your webhook integration, hit us up at support@punchlist.com or contact us here.

Verifying Authenticity of Webhook Calls

Webhooks provide an additional security measure to verify that the webhook is genuine and has come from Punchlist. This can be useful if you're looking to ensure only Punchlist webhook calls are being made to your endpoint, the information is genuine, and it hasn't been tampered with. These signatures will also help prevent replay attacks. Verifying the signing secret is optional.

Webhook requests will contain two headers that can be used to verify the request's authenticity:

x-punchlist-signature - The main signature 

x-punchlist-request-id - A unique ID for the given request

Avoiding Repeated Calls or Replay Attacks

The x-punchlist-request-id is a unique identifier for the request. If the request should fail, it'll be retried up to three times using the same ID. In no other circumstance will two calls have the same ID.

Verifying the Signature

The signature is generated using the HMAC and SHA256. In order to verify it, you must create a hash using your webhook secret and the payload's body, then compare it to the signature provided in the header x-punchlist-signature.

Represented simply: HMACSHA256(BODY)

Obtaining the Webhook Secret

The webhook secret can be retrieved from the Webhooks configuration in the Developer Settings.

Get Started With Punchlist’s Webhook Integration

Head over to your Punchlist dashboard to create your first webhook and start building your own custom integrations.