Types of webhooks available with Affinity's API

Help center reference

Reference — lookup information.

Get notified of events in your Affinity account by setting up webhooks with Affinity’s API V1. Webhook subscriptions can also be managed with API V2, where the webhook endpoints are currently in beta.

Note: If you’re currently trialing Affinity, you will not be able to access the Affinity API (and therefore set up webhooks) until you purchase one of the following tiers: Scale, Advanced, or Enterprise. Please see Getting started with the Affinity API + FAQs.

Important Callouts

• Every webhook is sent as type (the event name), body (the object), and sent_at (a Unix timestamp). Within an object type, the body has the same shape for each of its events, except where a “Note:” says otherwise. Not every object type has all three of created, updated and deleted — see Supported events.
• Each Affinity instance can have up to three webhook subscriptions.
• Each subscription can listen to specific events. Leave out the subscriptions parameter, or pass an empty array, to receive every event.
• If a webhook can’t be delivered because of a timeout or a connection problem with your URL, Affinity retries with an exponential backoff for up to 10 hours. If delivery still fails, the subscription is disabled and your Affinity admin and technical contacts get an email.
• Webhooks are set up with API V1. Webhook endpoints are also available in API V2, currently in beta. See “Differences between API V1 and API V2” in Getting started with the Affinity API + FAQs.

Frequently Asked Questions

Do webhooks count toward my API credits?

• Creating, updating, and deleting the webhook URL or making any changes to the subscription will count towards your API credits.
• API events sent to your URL do not count towards your API credits.

What events do not trigger webhooks?

• Auto-enriched field values will not trigger webhooks (this includes Affinity Data, PitchBook, Dealroom.co fields, and the enriched fields provided by Affinity).
  • Webhooks will only get triggered within auto-enriched fields if a user decides to manually add values to these fields or delete these manually-added values in the future.
• Field webhooks aren’t sent for Crunchbase fields, and field value webhooks for Crunchbase fields are sent with null values.

Do imports trigger webhooks?

Yes. Importing data into Affinity changes field values, and those changes fire webhooks like any other edit.

Undoing an import also triggers webhooks, because the undo changes values back to a previous state. Treat the undo as a second set of changes rather than a mirror image of the first — the data may have moved on between the import and the undo, so the events it generates will not necessarily be the exact inverse.

If you have webhook subscriptions, size the expected volume before running a large import — see the next question.

How many webhooks will an import send?

Three things multiply:

1. Rows actually changed. Rows whose values do not change generate no events.
2. One edit can produce more than one event. A single field value change commonly arrives as a field_value.deleted for the old value followed by a field_value.created for the new one, rather than a single field_value.updated. Subscribe to all three event types and treat them as a stream of changes — don’t assume one event per edit.
3. Each subscription is delivered separately. If three subscriptions listen for field_value.created, one created event leaves Affinity as three webhooks.

Put together, the volume is:

(rows changed) × (events per change — often 2, sometimes 1) × (subscriptions listening)

Worked example — an import that changes one field on 100 rows, with three subscriptions listening to both created and deleted:

• 100 rows × up to 2 events = up to 200 events
• 200 events × 3 subscriptions = up to 600 webhooks

Plan for the upper bound.

If you later undo the import, budget for a second wave of webhooks on top.

If you use webhooks to track ownership or status, expect to see removals as well as additions when values change. This is expected behaviour, and the resulting data in your CRM is correct.

Supported events

These match the supported webhook events in the API V1 documentation.

Object	Events
List	list.created, list.updated, list.deleted
List Entry	list_entry.created, list_entry.deleted
Note	note.created, note.updated, note.deleted
Field	field.created, field.updated, field.deleted
Field Value	field_value.created, field_value.updated, field_value.deleted
Person	person.created, person.updated, person.deleted
Organization	organization.created, organization.updated, organization.deleted, organization.merged
Opportunity	opportunity.created, opportunity.updated, opportunity.deleted
File	file.created, file.deleted
Reminder	reminder.created, reminder.updated, reminder.deleted

Types of Webhooks

Organization

Please note that the “Organization merged” webhook will provide a different response.

{
  "type": "organization.created",
  "body": {
    "id": 64779194,
    "name": "Affinity",
    "domain": "affinity.co",
    "domains": ["affinity.co"],
    "crunchbase_uuid": null,
    "global": true
  },
  "sent_at": 1636645351
}

Organization Merged

{
  "type": "organization.merged",
  "body": {
    "changer": {
      "id": 38706,
      "type": 1,
      "first_name": "John",
      "last_name": "Doe",
      "primary_email": "[e-mail]",
      "emails": []
    },
    "removed_company": {
      "id": 64779194,
      "name": "Affinity",
      "domain": "affinity.co",
      "domains": ["affinity.co"],
      "crunchbase_uuid": null,
      "global": true
    },
    "company": {
      "id": 64779195,
      "name": "Affinity 2",
      "domain": "affinity.co",
      "domains": ["affinity.co"],
      "crunchbase_uuid": null,
      "global": false
    },
    "merged_at": "2021-11-15 13:45:16 -0800"
  },
  "sent_at": 1637012717
}

Person

Please note that organization_ids is not returned when a Person is deleted.

{
  "type": "person.created",
  "body": {
    "id": 38706,
    "type": 0,
    "first_name": "John",
    "last_name": "Doe",
    "primary_email": "[e-mail]",
    "emails": [],
    "organization_ids": []
  },
  "sent_at": 1636645209
}

Opportunity

Please note that organization_ids and person_ids are not returned when an Opportunity is deleted.

If an opportunity is restricted, it’ll additionally have a is_restricted property. Field value webhooks for a restricted opportunity include is_restricted too. See Restricted opportunities.

{
  "type": "opportunity.created",
  "body": {
    "id": 7460748,
    "name": "Amazon - Project A",
    "person_ids": [],
    "organization_ids": []
  },
  "sent_at": 1636645558
}

List

{
  "type": "list.created",
  "body": {
    "id": 450
  },
  "sent_at": 1636642627
}

List Entry

{
  "type": "list_entry.created",
  "body": {
    "id": 16367,
    "list_id": 450,
    "creator_id": 38706,
    "entity_id": 287125,
    "entity_type": 1,
    "created_at": "2021-11-11 06:58:31 -0800",
    "entity": {
      "id": 84547971,
      "type": 1,
      "first_name": "John",
      "last_name": "Doe",
      "primary_email": "[e-mail]",
      "emails": ["[e-mail]", "[e-mail]"]
    }
  },
  "sent_at": 1636642712
}

Field

{
  "type": "field.created",
  "body": {
    "id": 59,
    "name": "Deals Amount",
    "list_id": 11,
    "value_type": 3,
    "allows_multiple": false,
    "track_changes": false,
    "dropdown_options": [],
    "ip_address": "206.253.143.17"
  },
  "sent_at": 1636644238
}

Field Value

A single change may arrive as a field_value.deleted followed by a field_value.created rather than a field_value.updated. Don’t rely on field_value.updated alone to catch every change — subscribe to all three event types.

entity_type and value_type use the Field Entity Types and Field Value Types from the API V1 documentation (for example, entity_type 0 is a person).

{
  "type": "field_value.created",
  "body": {
    "id": 250616,
    "field_id": 318500,
    "list_entry_id": null,
    "entity_type": 0,
    "value_type": 5,
    "entity_id": 91407761,
    "value": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "continent": null,
      "street_address": null
    },
    "field": {
      "id": 318500,
      "name": "Location",
      "list_id": null,
      "value_type": 5,
      "allows_multiple": false,
      "track_changes": false,
      "dropdown_options": []
    }
  },
  "sent_at": 1636635565
}

Notes

{
  "type": "note.created",
  "body": {
    "id": 22984,
    "creator_id": 860197,
    "person_ids": [38706, 89734],
    "is_meeting": false,
    "organization_ids": [],
    "opportunity_ids": [],
    "parent_id": null,
    "content": "Had a lunch meeting with Jane and John today.",
    "created_at": "2021-11-11 07:21:10 -0800",
    "ip_address": "206.253.143.17"
  },
  "sent_at": 1636644072
}

File

{
  "type": "file.created",
  "body": {
    "id": 43212,
    "name": "JohnDoeFriends.csv",
    "size": 993,
    "person_id": 10,
    "organization_id": null,
    "opportunity_id": null,
    "created_at": "2021-11-11 07:54:36 -0800",
    "uploader_id": 64056952
  },
  "sent_at": 1636646078
}

Reminder

The body is the reminder, in the same shape as the Reminder resource in the API V1 documentation.