Events
Receive signed events about connections, setup links and app changes, verify them with parseEvent, and manage deliveries.
fastn can tell your backend when something happens: a customer connected an app, a setup link was used, or a record changed in a customer's app. You register an https endpoint once (an event subscription). fastn then sends each event to it as a signed POST.
Register your endpoint
const hook = await fastn.webhooks.create({
url: "https://hooks.example.com/fastn/events",
eventTypes: ["connection.connected", "connection.revoked", "connection.expired", "setup_link.completed", "setup_link.expired", "connector.event", "unified.event"],
description: "Production",
});
const webhookId = hook.id; // esub_…
const secret = hook.secret; // whsec_…: shown once, store it nowfastn.webhooks answers the subscription itself (no data wrapper). For one customer only, create it on the customer instead: customer.api.events.createEventSubscription({ … }) fills in the customer for you, and that endpoint receives that customer's events alone.
url
Yes
Your https endpoint. An http URL is refused with 400 VALIDATION_ERROR; a private or internal address is refused with 400 EVENT_SUBSCRIPTION_URL_NOT_ALLOWED.
eventTypes
No
Which events to send (table below). Leave it out for every connection and setup link event. connector.event, unified.event and workflow.event are sent only when you list them.
connectors
No
connector.event only: just events from these apps (slug or connector id), for example ["hubspot"].
providerEvents
No
connector.event only: just these app event names, for example ["contact.creation"].
entities
No
unified.event only: just these entities, as category/entity, for example ["crm/contact"].
workflowEvents
No
workflow.event only: just these event names (the names your workflows pass to fastn.events.emit). Empty means every name.
description
No
Your label.
enabled
No
Default true.
Answer: the subscription itself, { id, url, orgId, eventTypes, connectors, connectorCategories, providerEvents, entities, workflowEvents, payloadTemplate, enabled, description, createdBy, createdAt, updatedAt, secret }. The raw operation fastn.events.createEventSubscription answers the same object wrapped as { data: { … } }. The secret is returned only here: reading the subscription later never shows it.
Event types
type
Sent when
Fields on top of the common ones
connection.connected
A customer connected an account, or signed in to it again.
app, connectionId, connectionName, and when known account, setupLinkId, metadata
connection.revoked
An account was removed.
app, connectionId
connection.expired
The app rejected the stored login; the customer must sign in again.
app, connectionId, reason (for example needs_reauth)
setup_link.completed
The customer finished a setup link.
setupLinkId, installationId, connections (app slug → connectionId), metadata
setup_link.expired
A setup link expired unused.
setupLinkId, metadata
connector.event
A change in a customer's app, for example a new HubSpot contact. Needs an app event trigger.
app, connector, connectionId, event (the app's event name), accountId, triggerId, payload (the app's own body)
unified.event
The same app change, as a unified record. Needs an app event trigger.
app, connector, connectionId, category, entity, action (created, updated or deleted), remoteId (the record id in the app), providerEvent, triggerId, and record (the unified record { id, provider, data }) or recordError (why it could not be read)
workflow.event
A workflow sent an event with fastn.events.emit. Opt in: sent only when you list it, filtered by workflowEvents.
event (the name the workflow gave it), workflowId, executionId, payload (the data the workflow sent), and when set app, connector, installationId
endpoint.test
You sent a test with testEventSubscription.
None
Every event carries id (evt_…), type, occurredAt, and tenantRef and orgId (your customer id: match on this). metadata is the object you set on the setup link.
Receive and verify events
Each delivery carries these headers:
X-Fastn-Signature
sha256= + HMAC-SHA256 of <timestamp>.<raw body>, keyed with your whsec_… secret.
X-Fastn-Timestamp
Unix seconds when the delivery was signed.
X-Fastn-Event-Id
The event id. It stays the same on every retry.
X-Fastn-Redelivery
true on an automatic retry. A replay starts the count again, so its first send does not carry it.
parseEvent checks the signature, refuses deliveries older than five minutes, and returns the event. Give it the raw body exactly as received: a re-serialized object changes the bytes and fails the check.
In production keep the seen ids in your database rather than in memory.
parseEvent(secret, headers, rawBody, opts?)
secret: your whsec_…. headers: the request headers (Node, Fetch Headers, or a plain object). rawBody: string or Buffer.
The event object plus headers (timestamp, signature, eventId, redelivery). Throws when the signature does not match or the timestamp is too old.
verifyEventSignature(secret, headers, rawBody, opts?)
Same as above.
true or false, without parsing.
readEventHeaders(headers)
The request headers.
{ timestamp, signature, eventId, redelivery }
signEventBody(secret, timestamp, rawBody)
The signature string fastn would send. Useful in your own tests.
opts.toleranceSeconds changes the five-minute window (default 300; 0 turns the age check off).
Test your handler without fastn by signing a body yourself:
Deliveries and retries
fastn retries a delivery with growing gaps for 24 hours, until your endpoint answers 2xx. After that the delivery is marked dead. The event id never changes, so drop repeats by id.
Send a test event
fastn.webhooks.test(id)
{ eventId, status: "queued" }. Sends one endpoint.test event.
See deliveries
fastn.webhooks.deliveries(id, { limit? })
[ { id, eventId, type, status, attempts, lastStatus, lastError, nextAttemptAt, createdAt, deliveredAt } ], newest first. limit defaults to 50, at most 200. status is pending, delivered or dead; the API does not filter on it, so filter the list yourself.
Send one again
fastn.webhooks.replay(deliveryId)
{ id, status: "pending" }. Sends the delivery again with the same event id, on a fresh retry schedule (attempts start again at 0). Works for dead deliveries too.
Pause or change
fastn.webhooks.update(id, { url?, eventTypes?, connectors?, providerEvents?, entities?, description?, enabled? })
The updated subscription. With enabled: false, deliveries are held and checked again every 5 minutes; a delivery still held 24 hours after it was created is marked dead. Enable the webhook again within 24 hours, or replay the dead deliveries.
Read
fastn.webhooks.get(id) / fastn.webhooks.list()
The subscription(s), without the secret.
New secret
fastn.webhooks.rotateSecret(id)
A new secret, returned once. Deliveries after this are signed with it.
Remove
fastn.webhooks.delete(id)
{ id, deleted: true }. Queued deliveries go with it.
The same calls exist as raw operations under fastn.events (createEventSubscription, listEventDeliveries, …) with { data } answers.
App events: watch a customer's app
connector.event and unified.event come from changes inside a customer's app. fastn listens for them only after you turn them on for that customer's account:
customer.watch(app, events, { accountId?, connectionId?, name? })
Turns the events on. Events are named in plain words (contact.created, deal.stageChanged) or as the app names them; an unknown name is 400 EVENT_NOT_FOUND with the valid list. The customer's account on the app is found from their connections: none is 404 CONNECTION_NOT_FOUND, several is 409 CONNECTION_AMBIGUOUS (pass connectionId). Two plain names that map to one app event are sent once; a connectionId of another app is 400 CONNECTION_MISMATCH. accountId is the app's own account id when the app needs one (the HubSpot portal id).
customer.watchableEvents(app)
The app's own event rows, { id, label, description, payloadSchema }. The plain names watch accepts (contact.created) are SDK aliases and are not in this list.
customer.watches(app?)
The customer's watches, every page.
customer.unwatch(app) / customer.unwatch(watchId)
Removes the watches on an app, or one watch; answers the ids removed. A watch id that is not this customer's is 404 WATCH_NOT_FOUND.
HubSpot has no stage-only event: deal.stageChanged maps to deal.propertyChange; filter on propertyName === "dealstage" in the event.
Each change then arrives as a connector.event (the app's own body) and a unified.event (the record in unified fields) on every webhook that lists those types.
Underneath: app event triggers
watch creates an app event trigger. The raw calls are still there when you need them. First list the events an app offers:
name
Yes
Your label.
connectorId
Yes
The app's id: connectorId of the connection.
connectorName
Yes
The app's name, for example HubSpot.
events
Yes
The app events to receive, each { id, label }, from listConnectorEvents.
connectionId
For a customer's account
The connection the events are for.
accountId
When the app needs it
The app's own account id, for example the HubSpot portal id or a Facebook Page id.
type
No
WEBHOOK or POLLING.
status
No
ACTIVE or DISABLED.
List triggers with fastn.events.listAppEventTriggers() and remove one with fastn.events.deleteAppEventTrigger({ id }). See also App event triggers and, for the events fastn received, Events.
Last updated
Was this helpful?

