While many integrations rely on Pipefy reaching out to external tools to fetch data, sometimes you need external tools to push data directly into Pipefy in real-time. This is exactly what the Webhook connector does.
Think of a Webhook as a dedicated phone number for your integration flow. External applications can "call" this URL and deliver a payload of data (usually in JSON format) exactly when an event happens on their side.
1. The Trigger: Catch Webhook
To start a flow when an external system sends data, you must use the Catch Webhook trigger.
When you add this trigger to your flow builder, Pipefy automatically generates a unique, secure URL. You will copy this URL and paste it into the configuration settings of the external application you want to connect with.
How to test it: Before building the rest of your flow, click Test Trigger and trigger an event in the external system. Pipefy will "catch" the payload, allowing you to map those incoming data fields (like names, IDs, or statuses) into subsequent steps in your flow.
2. The Action: Return Response (Synchronous Webhooks)
By default, when an external system sends a payload to a webhook URL, the integration engine immediately replies with a standard 200 OK to acknowledge receipt, and then processes your flow asynchronously in the background.
However, some external systems require a custom reply after the data is processed. For example, a third-party billing system might send an invoice and wait for your Pipefy flow to reply with a specific confirmation ID or an error message.
To do this, use the Return Response action at the end of your flow.
When configuring the Return Response action, you can define:
Status Code: The HTTP status code to return (e.g.,
200for Success,400for Bad Request, or201for Created).Headers: Custom HTTP headers needed by the destination system.
Body: The actual data payload (usually JSON) you want to send back.
Note: To use the Return Response action effectively, ensure the external system is configured to wait for a synchronous response.
3. Webhook Technical Limits
To ensure high performance and stability, the integration engine enforces specific limits on incoming webhook payloads. Please keep these limits in mind when configuring external systems to send data to Pipefy:
Webhook Timeout: For synchronous webhook requests (where the external system waits for a "Return Response" action), the maximum waiting time is 30 seconds. If your flow takes longer than 30 seconds to reach the Return Response step, the engine will return an HTTP
408 Request Timeouterror.Maximum Payload Size: The absolute maximum size for an incoming webhook payload is 5 MB. If an external system attempts to send a payload larger than 5 MB, the webhook will be rejected with an HTTP
413 Payload Too Largeerror.Fast Processing Limit (Inline Threshold): For optimal speed, keep your payloads under 512 KB. Payloads smaller than 512 KB are processed instantly in memory. Payloads between 512 KB and 5 MB are still accepted but are stored temporarily in file storage, which may add a slight delay to the processing time.
Best Practices
Secure your Webhooks: Since the Catch Webhook URL is public to anyone who knows it, it is highly recommended to validate incoming data. You can ask the external system to send a secret token in the Header, and use a Branch step right after the trigger to verify if the token matches your records before processing the data.
Keep it lean: If the external system sends a massive amount of data (approaching the 5 MB limit), consider changing the architecture. Instead of sending all the data in the webhook payload, configure the external system to send only a lightweight ID via webhook, and then use an HTTP action in Pipefy to securely fetch the full data record.