ceejay.events
Send an event of your own to the webhook subscriptions on your server.
This page is about events you send. To receive events from CEEJAY, and to check that they are real, see Verifying signatures.
The function takes the same last argument as every other, options: signal, timeoutMs
and maxRetries, for that one call, and idempotencyKey, as every write does. It can also
raise the errors any request can raise, such as a bad key or the rate limit. Both are on
Errors and retries.
ceejay.events.emit
Sends a custom event to every webhook subscription on your server that listens for it. A
subscription receives it when it lists that exact name, custom.event for every custom
event, or * for every event.
POST /v1/events/emit · requires events:emit · API reference: Emit an event
Retried by the SDK: Only with idempotencyKey. Without one, a retried event would be delivered twice
Takes one object, then options.
Prop
Type
Options
Prop
Type
CEEJAY calls the subscriptions one after another, with up to 5 seconds for each, and
responds when all have been attempted. The call takes as long as the subscribers do. With many
slow subscribers, give the call more time with timeoutMs.
Every subscription receives the event with the same id, signed the way CEEJAY signs every
delivery.
Returns Schemas['EmitEventResult'].
Prop
Type
CEEJAY retries a failed delivery later. You do not need to send the event again.
Errors
| Status | code | When |
|---|---|---|
400 | bad_request | The name is missing, too long or contains a character that is not allowed, or data is nested too deeply or contains text that is not valid Unicode |
404 | not_available | This instance has no webhook subscriptions yet |
An event that got no response. A sent event cannot be recalled. With a key, CEEJAY
does not send the event again when it cannot tell whether the first attempt was sent: the call
fails with status 409 and the code idempotency_outcome_unknown. Details about
idempotency keys are on Errors and retries.
Example
const sent = await ceejay.events.emit(
{
event: 'match.finished',
data: { matchId: 'm_8841', winner: '409876543210987654', score: [3, 1] },
},
{ idempotencyKey: 'match-m_8841:finished', timeoutMs: 60_000 },
)
console.log(`${sent.event} went to ${sent.subscribersNotified} subscribers`)
for (const result of sent.results) {
if (result.status === 'failed') console.log(result.name, result.error)
}
