Skip to main content

​
Webhooks

​
Overview

Webhooks let your application receive real-time HTTP notifications when events occur in Animo (new submissions, lead changes, meeting bookings, etc.). Use the API to register, update, and remove webhook endpoints. This documentation covers webhook management endpoints only (register, update, remove). Event delivery is handled by Animo when events occur.

​
Prerequisites

  • Company subscription must include USE_INTEGRATIONS.
  • Token must include at least one *:subscribe scope matching the events you want to receive.

​
Webhook events

Event valueScope requiredDescription
activation-submittedactivations:subscribeNew activation submission
form-submittedsubmissions:subscribeNew form submission
lead-createdleads:subscribeLead created
lead-updatedleads:subscribeLead updated
lead-deletedleads:subscribeLead deleted
meeting-bookedmeetings:subscribeMeeting booked
meeting-updatedmeetings:subscribeMeeting updated
meeting-cancelledmeetings:subscribeMeeting cancelled
You can only subscribe to events permitted by the subscribe scopes on your token.

​
Endpoints

​
Attach webhook

  • Method: POST
  • Path: /api/v1/{company}/webhooks/attach
  • Scope: At least one of activations:subscribe, submissions:subscribe, leads:subscribe, meetings:subscribe
  • Subscription: USE_INTEGRATIONS

​
Request body

{
  "name": "My integration",
  "url": "https://example.com/webhooks/animo",
  "events": [
    "activation-submitted",
    "lead-created",
    "form-submitted"
  ]
}
FieldRequiredDescription
nameYesUnique name per user (max 255 chars)
urlYesHTTPS callback URL (max 255 chars)
eventsYesArray of webhook event values (must match your token scopes)

​
Response 201

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My integration",
    "token": "random32charSecretToken...",
    "url": "https://example.com/webhooks/animo",
    "events": [
      "activation-submitted",
      "lead-created",
      "form-submitted"
    ],
    "created_at": "2026-06-01T12:00:00.000+00:00"
  }
}
Store the token securely — it is required to update or detach the webhook.

​
Response fields

FieldTypeDescription
idstringWebhook UUID
namestringWebhook name
tokenstringSecret token for update/detach
urlstringCallback URL
eventsarraySubscribed event values
created_atstringISO 8601 timestamp

​
Update webhook

  • Method: PATCH
  • Path: /api/v1/{company}/webhooks/update
  • Scope: Matching subscribe scope(s) for any events being set
  • Subscription: USE_INTEGRATIONS

​
Request body

At least one of name, url, or events must be provided (along with id and token). 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "random32charSecretToken...",
  "url": "https://example.com/webhooks/animo-v2"
}
FieldRequiredDescription
idYesWebhook UUID
tokenYesSecret token from attach response
nameNoNew name
urlNoNew HTTPS URL
eventsNoNew event array

​
Response 200

Returns the updated WebhookResource.

​
Errors

StatusWhen
422Invalid token or validation failure

​
Detach webhook

  • Method: DELETE
  • Path: /api/v1/{company}/webhooks/detach
  • Scope: Any subscribe scope (token must be valid)
  • Subscription: USE_INTEGRATIONS

​
Request body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "random32charSecretToken..."
}

​
Response 204

Empty body on success.