Receive a webhook event
const url = 'http://localhost:11044/api/v1/webhooks/example';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '"example"'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/webhooks/example \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '"example"'Receives a JSON payload from an external system. If the source has a configured action, the event is processed immediately; otherwise the payload type is inferred and the event is queued until the user configures an action via the UI. Provider URL-validation handshakes (such as an endpoint.url_validation event) are answered synchronously with the scheme-specific response body instead of the processed/queued shape.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Source identifier for the webhook (e.g., ‘github’, ‘stripe’)
Request Bodyrequired
Section titled “Request Bodyrequired”The provider’s payload: a single JSON event object, or an array of them for providers that batch. Taken as RAW BYTES rather than a parsed type because the signature is computed over the bytes exactly as sent — reserializing a parsed body would change them and every signature check would fail. An empty body is read as an empty object. Non-object elements of an array are ignored rather than refused.
Example generated
exampleResponses
Section titled “Responses”Event processed successfully, or handshake response body
A batch of events, counted by outcome. Answers 200 when any ran, 202 when any queued, and 500 only when EVERY event failed
object
How many events the body carried
How many threw. A partial failure still answers 200 or 202, so a caller must read this rather than the status code
How many were dispatched and ran
How many were queued against an unconfigured source
Always batch
A single event was dispatched to its handler and ran
object
Whatever the handler returned, verbatim and unshaped — a handler’s output is the handler’s business
Always processed
A single event was accepted but not dispatched, because its source is not configured yet
object
Why it was queued rather than handled, written to be shown
The source the event was queued against
Always queued
The request was refused: 400 for a body that would not parse, 500 for a dispatch that threw
object
What went wrong, written to be shown
Always error
The caller was not admitted: signature verification, tenant resolution or source installation failed
object
Which check refused it. Deliberately coarse — a precise reason would tell an attacker which half of the credential was wrong
Always unauthorized
A provider’s URL-registration handshake. THIS SHAPE IS THE PROVIDER’S, not this API’s: Zoom requires exactly these two fields and no status, so it must not be made to resemble the other receipts.
object
The hex HMAC-SHA256 of plainToken, keyed by the provider’s stored webhook secret
The token the provider sent, echoed back unchanged
Event queued (unknown source, awaiting configuration)
A batch of events, counted by outcome. Answers 200 when any ran, 202 when any queued, and 500 only when EVERY event failed
object
How many events the body carried
How many threw. A partial failure still answers 200 or 202, so a caller must read this rather than the status code
How many were dispatched and ran
How many were queued against an unconfigured source
Always batch
A single event was dispatched to its handler and ran
object
Whatever the handler returned, verbatim and unshaped — a handler’s output is the handler’s business
Always processed
A single event was accepted but not dispatched, because its source is not configured yet
object
Why it was queued rather than handled, written to be shown
The source the event was queued against
Always queued
The request was refused: 400 for a body that would not parse, 500 for a dispatch that threw
object
What went wrong, written to be shown
Always error
The caller was not admitted: signature verification, tenant resolution or source installation failed
object
Which check refused it. Deliberately coarse — a precise reason would tell an attacker which half of the credential was wrong
Always unauthorized
A provider’s URL-registration handshake. THIS SHAPE IS THE PROVIDER’S, not this API’s: Zoom requires exactly these two fields and no status, so it must not be made to resemble the other receipts.
object
The hex HMAC-SHA256 of plainToken, keyed by the provider’s stored webhook secret
The token the provider sent, echoed back unchanged
Body is not valid JSON, or not an object or array of objects
The request was refused: 400 for a body that would not parse, 500 for a dispatch that threw
object
What went wrong, written to be shown
Always error
Signature verification or tenant resolution failed
The caller was not admitted: signature verification, tenant resolution or source installation failed
object
Which check refused it. Deliberately coarse — a precise reason would tell an attacker which half of the credential was wrong
Always unauthorized
Every event in the batch threw. A PARTIAL failure answers 200 or 202 with a non-zero errors count instead
The request was refused: 400 for a body that would not parse, 500 for a dispatch that threw
object
What went wrong, written to be shown
Always error
A batch of events, counted by outcome. Answers 200 when any ran, 202 when any queued, and 500 only when EVERY event failed
object
How many events the body carried
How many threw. A partial failure still answers 200 or 202, so a caller must read this rather than the status code
How many were dispatched and ran
How many were queued against an unconfigured source
Always batch