Use POST to URL (Webhook) to send card details to an external system when your automation's trigger and conditions qualify. You need the receiving system's webhook URL and someone who can check what it receives.
This is an automation action, not an incoming API request that creates cards in Aptly. It is also separate from the board-level webhook configuration in the developer API.
Before You Begin
- Choose the board and the event or conditions that should send data.
- Obtain the receiving system's approved HTTPS webhook URL. Confirm that it is a receiving endpoint, not a sign-in page or an Aptly card-import URL.
- Confirm the receiver's expected data, authentication requirements, and intended downstream action with its owner.
- Prepare a nonproduction endpoint and a dedicated card with sample data. Do not use a public request collector for real resident or customer information.
- Arrange access to the receiver's request history and resulting records. Agree how the receiving workflow will handle duplicates and failures.
Aptly sends a fixed card-data payload, the request body containing the card details. Build the receiving workflow from an inspected sample; do not assume its exact field names or structure match a card API response. Aptly does not automatically retry this action.
Example: Hand Off a New Lead
Suppose your team wants an approved external system to receive a lead when its card first enters your new-lead stage.
- Trigger: On Stage Change
- Stage: your board's new-lead stage
- Action: POST to URL (Webhook)
- Destination during testing: the receiver's nonproduction endpoint
- When: Immediately, with the office-hours choice reviewed
- Expected result: the receiver records the sample request and produces only the intended test handoff
Use the actual stage and destination for your workflow. On Stage Change runs once for that card in the selected stage; use Understanding Automation Triggers: Stage Change vs. Custom Condition if the handoff needs to repeat.
Create the Draft
- Open the board's Automations window and select New Automation.
- Enter a descriptive Title, such as Webhook: New lead handoff. Keep Status: Draft.
- Select the trigger and conditions that should send the card.
- Select POST to URL (Webhook) under Action.
Configure the Webhook
- Enter the receiver's approved nonproduction URL and verify the full address.
- Select When and review Only fire if office is open. The example uses Immediately; the queue still applies.
- Keep Status: Draft and select Save. Reopen the rule to confirm the destination and scope.
The editor has no custom header or body controls. If the receiver needs authentication headers or a different payload, agree how it will accept or adapt the request. Do not put an Aptly API key in the URL.
When is shared across all actions. Review and test each action in a multi-action rule.
Review, Test, and Go Live
Do not assume Test Mode blocks external webhook requests. Use sample data and a nonproduction receiver under your team's control.
- Review the sample card, every action, and the nonproduction URL. Have the receiver's owner ready to inspect requests. Test email and phone destinations do not replace the webhook URL.
- Save in Test Mode and run Test Automations → Test on a selected card. Compare Aptly's result with the receiver's request history, required values, missing-value handling, and downstream test result.
- Check a card that should not qualify. Select Verified after reviewing the results; this records your acknowledgment, not automatic validation.
- When the receiving workflow is production-ready, recheck the approved production URL, scope, and timing. Set Status: Live, select Save, and verify the first result in both systems and Aptly's Logs.
See Using Test Mode for Automations for the full test process.
Check the receiver before repeating a test; an unclear Aptly result does not prove the external action failed. If anything is unexpected, save in Draft. This does not undo data already sent or the receiver's work.
Troubleshoot a Webhook
The Receiver Has No Request
Check the saved Status, qualifying card, trigger, When, office hours, and destination URL. Review Aptly's Logs and ask the receiver's owner to check availability and request history.
The Receiver Rejected the Request
Use the receiver's error details to check its required authentication, content format, and fields. Confirm compatibility before retrying; a valid URL alone does not establish that the receiver accepts the payload.
A Request Arrived but No Handoff Was Created
Inspect the receiving workflow's mapping, required values, filters, and processing history. Receiving a request and completing the downstream action are separate checks.
Duplicate Handoffs Appeared
Check repeated tests, overlapping Live automations, and recurring conditions. Review the receiver's duplicate-handling logic before sending again.
There are no automatic retries. Resolve the receiving system's problem and check whether the original request already produced a result before arranging another send. If you need help, provide the automation title, sample card, approximate time and time zone, and error details without exposing secrets or sensitive payload data.