Article

    Send data to Ahoy with webhooks

    4 min read
    Last updated 4 hours ago

    A webhook lets another system push data into Ahoy the moment something happens – a signup on your website, a lead from an outreach tool, a row in your own database. Each request can create or update a contact, add a note to their timeline, and set properties.

    Before you begin

    • Someone technical. The sending system needs to make an HTTP request, so you'll want a developer or a tool like Zapier or n8n.
    • A contact identifier. Every request needs an email address or a LinkedIn URL, so Ahoy knows who it's about.

    Set it up

    1. Go to Settings → Developers → Webhooks.
    2. Under Webhook & extension keys, enter a key name and create the key.
    3. Copy the key straight away. You won't see it again.
    4. Open Keys and request format and copy the webhook URL.
    5. Have your system send a POST request with a JSON body to that URL, with the key in a header.

    Use either header:

    X-Api-Key: your-api-key
Authorization: Api-Key your-api-key

    What to send

    BlockRequiredWhat it does
    contactYesIdentifies the person. If a contact with the same email or LinkedIn URL exists, it's updated. If not, one is created
    timeline_eventNoAdds something to the contact's timeline, such as a note
    propertiesNoSets built-in or custom properties on the contact
    write_modeNoSet to overwrite to replace existing values. By default, only empty fields are filled
    idempotency_keyNoA unique value per event, so a retry doesn't create a duplicate

    Example

    {
  "contact": {
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Acme Corp"
  },
  "timeline_event": {
    "type": "note",
    "content": "Signed up for the waitlist"
  },
  "idempotency_key": "signup-10482"
}

    The settings page has more examples you can copy, the full list of fields, and the responses you'll get back.

    Good to know

    • Existing data is safe by default. Without write_mode set to overwrite, a webhook only fills fields that are empty.
    • Unknown properties are rejected. If you send a property that doesn't exist, the request fails and tells you which one. Create the property first. See Create and manage fields.
    • Send each field once. Put the email in contact or in properties, not both.
    • Keys can be deleted. Delete a key on the same page and anything using it stops working.

    Website forms don't need a webhook

    To capture form submissions from your website, add the Ahoy tracking code instead. There's nothing to build. See Capture website form submissions.

    Inbound webhooks for automations

    The same page has an Inbound webhooks list, managed by account admins. Each one has its own URL and feeds an automation. Writing your own automations isn't available in every workspace yet, so contact us if you need this.

    Need help?

    Email help@ahoy.ai or message us in your shared Slack channel.

    Related articles