Help center
Open dashboard

Webhooks

Automate workflows and connect Atarim to tools that don’t have a built-in integration.

Atarim team Updated 7 Aug 2026 · 10 min read
Integrations
Atarim webhook settings with endpoint URLs for task and comment triggers
Before you start

Relevant for

  • Project Managers, Developers, and Operations Teams building custom automations.

Required knowledge

  • A basic understanding of webhooks and an automation tool such as Zapier or Make.

Tools & resources needed

  • An Atarim account on a plan that includes integrations.
  • An automation tool or endpoint that supports webhooks with custom headers.

Webhooks let Atarim exchange data in real time with external tools — Zapier, Make, Asana, Basecamp and anything else that speaks the format. They are the general-purpose option when no purpose-built integration exists, and they work in both directions.

Webhooks are the general-purpose option when no purpose-built integration exists.

At the heart of an efficient workflow is having the right information at the right time. Webhooks let Atarim exchange data in real time with external tools — Zapier, Make, Asana, Basecamp and anything else that speaks the format. You can receive notifications when events happen in Atarim, automate work in other systems, and keep data in sync so teams stay aligned.

What Are Webhooks?

A webhook is a way for two applications to send data to one another automatically. When a specific event happens in Atarim — a task being created, say — a webhook sends an HTTP POST request to a URL you have configured, known as the webhook endpoint.

Because webhooks are a standard format used across the web, developers can write their own code to receive and process the payload. That is what makes it possible to automate processes and sync tools with no direct Atarim integration at all.

Atarim supports them in both directions: outgoing webhooks (pull) fire when an event occurs in Atarim, and incoming webhooks (push) let an external system make something happen inside Atarim. Used together they give you bi-directional automation, so both systems stay in step without anyone copying between them.

Should You Use Webhooks at All?

Usually not. Atarim has built-in integrations for Zapier, Make and Pabbly that handle the connection for you, and they are worth preferring for four reasons.

  • A simpler setup process
  • Pre-configured triggers and actions
  • Compatibility that is tested and maintained
  • Better performance and reliability in most cases

    • Reach for manual webhooks when you need a custom automation, your tool is not supported natively, or you are working in a system you have built yourself.

    Check the built-in integrations first
    Manual webhooks give you more control and considerably more ways to get it wrong. Explore Integrations

    Where to Find Them

    Both directions are configured on the same page — outgoing events in one list, incoming actions in another.

    Instructions:

  • From the main dashboard, select Settings.
  • Select Webhook under Integrations.
  • The Webhooks page opens, showing your outgoing and incoming webhook lists, your Webhook token, and the Custom Webhook section.
    • The Webhooks section in Atarim settings, showing the outgoing and incoming lists
    The Webhooks section — outgoing and incoming lists, plus your webhook token
    An outgoing webhook event row in Atarim with its URL, copy control and switch
    Each event has its own row — a name, a URL, a copy control and a switch

    Outgoing Webhooks: Sending Data Out of Atarim

    Also called pull webhooks. These fire when an event happens in Atarim and make its data available to your automation tool. Twelve events are available.

    EventFires when
    New TaskA task is created.
    Task CompletedA task is marked complete.
    New CommentSomeone comments on a task.
    New NoteAn internal note is added.
    New Status ChangeA task’s status changes.
    New Priority ChangeA task’s priority changes.
    New Assigned UserSomeone is assigned to a task.
    New TagA tag is applied.
    New Email TaskA task arrives by email.
    New Form SubmissionA form submission comes in.
    New GraphicA design is added.
    New WebsiteA website is added.

    Outgoing means Atarim publishes the event and your automation tool polls for it.

    Instructions:

  • In Zapier or Make, create a new automation and select Webhooks as the trigger app.
  • Choose Retrieve Poll as the trigger type. This periodically checks Atarim for new data, which suits Atarim’s outgoing webhooks.
  • In Atarim, go to Settings → Webhooks and find the event in the list. Each event has its own row showing its name, its URL, a copy control and a switch.
  • Switch the event on.
  • Select the copy control beside its URL, then paste it into the URL field in your automation tool.
  • Add the authentication header described below, then save and test.
    • An Atarim webhook URL pasted into an automation tool to retrieve data
    Your automation tool uses this URL to retrieve data from Atarim
    Tip
    Enable one event first and get it working end to end before adding others. Keep the URLs somewhere organised as you go — they look similar and are easy to mix up.
    New Note sends internal content
    Notes are hidden from clients inside Atarim, but an outgoing webhook delivers them wherever you point it. Do not enable this event if the destination is visible to people who should not see internal discussion. Learn More About Internal Tasks

    Authentication

    Atarim requires authentication on webhook requests, using an HTTP header. This applies in both directions.

    Instructions:

  • Find your Webhook token in the Webhooks section of Settings.
  • In your automation tool, add a custom header.
  • Set the header name to webhook-token and its value to your token.
  • Save.
    • Adding the webhook-token header in an automation tool
    The header name must be exactly webhook-token
    A missing token fails silently
    If the header is absent or wrong, the webhook simply does not work — you will not get an error explaining why. Always run a test after setting one up rather than assuming success.
    Note
    Treat the token as a credential. Anyone holding it can act against your workspace, so keep it out of chat, email and shared documents.

    Incoming Webhooks: Sending Data Into Atarim

    Also called action or push webhooks. These give you a URL that an external system calls with a POST request to make something happen in Atarim. Seven actions are available.

    ActionWhat it does
    Create TaskCreates a task in Atarim.
    Add CommentAdds a comment to a task.
    Add NoteAdds an internal note to a task.
    Add TagApplies a tag to a task.
    Assign UserAssigns someone to a task.
    Change StatusChanges a task’s status.
    Change PriorityChanges a task’s priority.

    Incoming runs the other way, with your tool posting to Atarim — and only POST is accepted.

    Instructions:

  • In your automation tool, create a new action and choose Webhooks as the action app.
  • Select POST as the method. POST is required — GET and PUT will not work.
  • In Atarim, go to Settings → Webhooks and find the action under Incoming Webhook (Actions/PUSH).
  • Switch the action on, then use the copy control beside its URL. Each action has its own URL, laid out the same way as the outgoing rows.
  • Paste the URL into the URL field of your action.
  • Set the content type and request body as described below.
  • Add the webhook-token header.
  • Test, then activate.
    • Configuring an incoming webhook action with the POST method
    POST is required for incoming actions
    The Incoming Webhook actions list in Atarim, each action with its own URL
    Each action has its own URL under Incoming Webhook (Actions/PUSH)

    Choosing the Content Type

    Automation tools ask you to set a content type for the request. The values below reflect what has worked reliably for each action; if a request is rejected, switching between JSON and form encoding is worth trying.

    ActionPayload type
    Create TaskJSON
    Add CommentJSON
    Add NoteForm
    Add TagJSON
    Assign UserForm
    Change StatusJSON
    Change PriorityJSON
    Tip
    For form-encoded requests, enter each key and value as a separate pair in your tool rather than pasting a block. In Zapier in particular, pasting JSON into a form-encoded action is a common cause of rejected requests.

    Building the Request Body

    Most actions identify the task using its dashboard URL, then carry the value you want to apply.

    ActionRequired parameters
    Create Tasksite_uuid, site, page_uuid, page, message, users, urgency, status
    Add Commenttask_uuid, comment_content, complete_task
    Add Notetask_uuid, comment_content, complete_task
    Add Tagtask_uuid, value
    Assign Usertask_uuid, users
    Change Statustask_uuid, value
    Change Prioritytask_uuid, value
    A request body configured for an Atarim incoming webhook action
    The request body carries the parameters the action needs
    Entering key and value pairs for a form-encoded webhook request
    For form-encoded actions, enter each key and value as its own pair
    Tasks are identified by task_uuid
    Every action except Create Task needs it, and the request is rejected without it. Create Task uses site_uuid and page_uuid instead, since no task exists yet.
    Note
    complete_task is required on Add Comment and Add Note, and must be exactly yes or no. Omitting it fails validation even though it might look optional.

    Accepted Values

    ParameterAccepted values
    value for statusopen, in-progress, pending-review, complete
    value for prioritylow, medium, high, critical
    complete_taskRequired on Add Comment and Add Note. yes marks the task complete after the action; no leaves the status unchanged.
    Values must match exactly
    The status and priority values above are the only ones accepted. “In Progress” or “Pending Review” written as they appear in the interface will not work — use the hyphenated lowercase forms.
    Note
    The exact field names vary between automation tools. Zapier, Make and Pabbly each label the URL, method, content type and header sections slightly differently, so match the intent rather than looking for these exact words.

    Zapier Format Settings

    If you are building this in Zapier, two settings affect whether Atarim can read your payload.

  • Wrap request in array: No
  • Unflatten: Yes
    • The Wrap request in array and Unflatten settings in Zapier
    Wrap request in array: No, and Unflatten: Yes

    Custom Webhook

    The Custom Webhook section is where you paste a URL of your own — described in-product as letting you specify a URL where you can receive notifications. It is the route automation platforms use when they generate a webhook URL for you to register.

    It offers eight event fields, a subset of the outgoing list: New Website, New Task, New Comment, New Status, New Priority, New Tag, New Email Task, New Form Submission.

    Instructions:

  • Find Custom Webhook in the Webhooks section.
  • Paste your URL into the field for the event you want.
  • Save. Atarim posts that event’s data to your URL from then on, and a copy control lets you retrieve the value later.
    • The Custom Webhook section in Atarim with a field for each event
    Each event has its own field — the URL must go against the right one
    Match the URL to the right event
    Each event has its own field, so a URL pasted against the wrong one produces a connection that looks configured and never fires. Nothing warns you.
    Note
    The Custom Webhook list is shorter than the outgoing list, and two labels differ — it shows New Status and New Priority rather than New Status Change and New Priority Change. Task Completed, New Note, New Assigned User and New Graphic are not available here.

    FAQs

    Where do I find my webhook token?

    In the Webhooks section of Settings, shown as Webhook token.

    Do I need webhooks if I use Zapier, Make or Pabbly?

    Often not — those integrations handle the connection. Some setups still ask you to register a webhook URL in Atarim, so the two work together rather than being alternatives.

    Can I test before going live?

    Yes. Use your automation tool’s test function, or send a sample payload manually and check the result in Atarim.

    How does Atarim know which task to act on?

    Through task_uuid in the request body. Every action except Create Task requires it.

    Why is my request rejected?

    Usually a missing required parameter or a value outside the accepted list. Check task_uuid is present, and that status and priority values are lowercase and hyphenated.

    Can one webhook trigger several actions?

    Not directly — each action has its own URL. Multi-step automations in Zapier or Make can chain them.

    Do I need to write code?

    No. Zapier, Make and Pabbly cover most cases without any.

    Will an outgoing webhook send internal notes?

    Yes, if the New Note event is enabled. Webhooks do not apply the client-visibility rules that apply inside Atarim.

    Common issues

    • Nothing arrives at your URL — check the webhook-token header is present and correct. This fails silently.
    • Requests are rejected — check the required parameters are all present. task_uuid is needed by every action except Create Task, and complete_task is required on comments and notes.
    • A status or priority change does nothing — the value must match exactly, lowercase and hyphenated, such as in-progress.
    • The Webhooks section is locked — your plan does not include integrations. The lock names the minimum plan.
    • Data arrives for the wrong event — the URL is in the wrong Custom Webhook field. Each event has its own.
    • Internal notes reached an external tool — the New Note outgoing event is enabled. Remove its URL.
    • Zapier sends but Atarim ignores it — check Wrap request in array is No and Unflatten is Yes.
    • Some events work and others do not — only events with a URL saved will fire. Check each one you expect.

    Conclusion

    Webhooks cover what the built-in integrations do not: outgoing for telling other systems what happened, incoming for letting them act on Atarim.

    Three things account for most failures — a missing webhook-token header, the wrong payload type, and a value that does not match the accepted list. Check those first and most problems resolve quickly.

    Tips & best practices

    • Use the built-in Zapier, Make or Pabbly integrations before building webhooks by hand.
    • Always add the webhook-token header — without it, requests fail silently.
    • Include task_uuid on every action except Create Task.
    • Use the exact status and priority values, lowercase and hyphenated.
    • Enable one event at a time and confirm it works before adding more.
    • Validate payloads with your tool’s built-in tester, or with something like Postman if you are working outside an automation platform.
    • Filter in your automation tool so only relevant events trigger actions.
    • Enable error logging so failed events are visible rather than silent.
    • Think twice before enabling New Note, which carries internal content.

    Related articles