Skip to main content
Webhooks send an HTTP request to your server when a brand changes, or when a lookup that returned 202 finishes. You don’t have to poll.

​
Who can use webhooks

Webhooks are available on all paid plans. They belong to your team, so call the webhook routes with one of your team’s secret keys. Owners and admins can create, update, and delete endpoints, and rotate signing secrets. Other members can list endpoints and read their secrets. On the free plan, or without the right role, the webhook routes return 403 with code forbidden. See pricing for what each plan includes. Delivery has two parts:
  • Endpoints decide where events go. Manage them in the dashboard or through /v2/webhook_endpoints.
  • Subscriptions decide which brands send you brand.updated events. Manage them by brand id through /v2/brands/{id}/subscription.
Endpoints and subscriptions are free and have no rate limit. Each plan caps how many you can have. See plan limits.

​
Keep your data current

1

Create an endpoint

Create an endpoint, read its signing secret, and set your receiver to verify deliveries.
2

Look up a brand

Send a lookup such as GET /v2/brands?domain=apple.com. On 200, store data.id next to your own record, download the images you need, and save their etag values. Several of your records can point to the same brand id.
3

Handle a 202

Keep metadata.request_id. When a brand.indexed event with that request_id arrives, fetch data.brand_id if status is ready. Stop retrying if status is not_found.
4

Handle brand.updated

Find your records by the event’s data.brand_id, and fetch GET /v2/brands/{id}?nosubscribe=true. Update your records, and download again only the images whose etag changed.
5

Stop updates you don't need

Send DELETE /v2/brands/{id}/subscription, and add nosubscribe=true to later lookups of that brand.
Keep your own map from identifiers to brand ids. A refetch by id reports an id lookup, not the identifier you first sent.

​
Events

Every event has the same outer shape. An event tells you what happened, not what the brand looks like now. Fetch the brand for its data.

​
Brand updated

Logo.dev sends brand.updated when a brand you subscribe to changes.
changed_attributes lists what changed, in a fixed order and without repeats. It holds names and paths, never old or new values. A nested change lists the parent field, then each changed path under it. It can contain:
  • Brand fields: name, slug, description, domain, and colors
  • Logo paths: logo, logo.url, logo.etag, logo.blurhash, logo.source, and logo.last_updated_at
  • Brandmark paths: brandmark and the same five paths under it
  • social_banners, as one path. Read the whole array again, because no path names which banner changed.
  • Social paths: socials and socials.<network>, for facebook, github, instagram, linkedin, pinterest, reddit, snapchat, telegram, tumblr, twitter, wikipedia, or youtube
  • aliases, industry, and country_code. Logo.dev tracks these, but the brand object does not return them yet.
Fetch GET /v2/brands/{id}?nosubscribe=true for the current record. It can include changes newer than the event.

​
Brand indexed

brand.indexed tells you that a lookup which returned 202 has finished. You don’t subscribe to it. Logo.dev sends it for your own 202 responses when metadata.pending.webhook was true.
On ready, fetch the brand by id. A normal fetch also subscribes you to the brand, and nosubscribe=true skips that. On not_found, the original lookup now returns 404.

​
Verify deliveries

Logo.dev signs deliveries and sends them through Svix. Verify each signature with your endpoint’s signing secret before you act on the event. Svix’s receiving guide shows how, and also covers retries and replays.

​
Endpoints

An endpoint is an HTTPS URL that receives events. Endpoints belong to your team, and the dashboard shows the same endpoints.
Leave out filter_types, or send [], to receive every event type. The response does not include the signing secret. Read it from the secret route. Any team member can list and read endpoints and secrets. Creating, changing, deleting, and rotating need the owner or admin role. When you rotate a signing secret, the old secret keeps working for a grace period. Deploy the new one during that time so you don’t drop deliveries. Treat the secret as a credential.

​
Subscriptions

Logo.dev sends brand.updated events only for brands your account subscribes to. Your account has one subscription per brand, however you found the brand. You subscribe in two ways:
  • Automatically. With webhooks on, a GET /v2/brands or GET /v2/brands/{id} lookup subscribes you to the brand it returns. The lookup reports the result in metadata.subscription. At your plan’s subscription limit, the lookup still returns the brand, but it does not subscribe you, and metadata.subscription.status is quota_exceeded. Add nosubscribe=true to skip the subscribe. It does not remove a subscription you already have.
  • Explicitly. Send PUT /v2/brands/{id}/subscription.
Logo and brandmark lookups, search, and image downloads never subscribe you. A subscription follows the brand, not the identifier that found it. If a domain or ticker later matches a different brand, your subscription stays with the first one. Look your identifiers up again to catch that. Deleting a subscription stops events for every record of yours that points to the brand. A later lookup subscribes you again, unless it sends nosubscribe=true.

​
Plan limits

Each plan caps the number of webhook endpoints and the number of subscribed brands on your account. The pricing page lists the caps for each plan. A disabled endpoint still counts toward the cap. At the cap, POST /v2/webhook_endpoints and PUT /v2/brands/{id}/subscription return 409 with the code limit_exceeded. The message names your plan’s limit. To add another, delete an endpoint or unsubscribe from a brand, or upgrade your plan. A brand you already subscribe to stays subscribed at the cap.