MJS Developer Portal

Webhooks

Event delivery and observability

Integration connections emit webhook-related events. Inspect delivery history through the API and harden your receivers for TLS, authentication, and idempotency.

Event model

When an integration connection is active, the platform may POST event payloads to URLs you configure for that connector. Payload shapes vary by connector; fields exclude unrelated tenant data and follow least-necessary disclosure.

Use GET /api/v1/integrations/connections/:id/events (scope integrations:READER) to audit deliveries, retries, and processing outcomes from your automation pipeline.

curl -sS "https://<host>/api/v1/integrations/connections/<connection-id>/events" \
  -H "Authorization: Bearer mjt_<secret>"

Building a secure receiver

  • Expose an HTTPS endpoint with a valid certificate.
  • Authenticate inbound calls using connector-specific signing or shared secrets configured in the integration hub—not query-string tokens.
  • Respond quickly with 2xx after validating and enqueueing work; process asynchronously.
  • Implement idempotency using event identifiers to tolerate at-least-once delivery.
  • Reject unexpected content types and oversize bodies.

Outbound safety (platform side)

Platform-initiated webhook and alerting HTTP calls apply SSRF protections: disallowed private IP ranges, metadata endpoints, and unsafe redirects. Only register destinations on the public internet that your organization controls.

Details align with the Security guidance on SSRF.

Connection lifecycle and webhooks

Creating a connection (POST /api/v1/integrations/connections, integrations:OPERATOR) may enable webhook delivery once credentials are bound. Revoking a connection (POST .../revoke) stops new outbound events; your receiver should treat subsequent unsigned traffic as invalid.

Retries and failures

Transient delivery failures are retried with backoff. Persistent failures appear in the connection events log. Monitor that log from automation and alert your team when error rates exceed your SLO.

Minimal handler sketch (server-side)

// Pseudocode — verify signature per connector docs before trusting body
app.post("/hooks/mjs-integration", (req, res) => {
  if (!verifyConnectorSignature(req)) {
    return res.sendStatus(401);
  }
  const eventId = req.body.id;
  if (alreadyProcessed(eventId)) {
    return res.sendStatus(200);
  }
  queue.enqueue(req.body);
  markProcessed(eventId);
  res.sendStatus(200);
});

Never log full webhook payloads in clear text if they may contain personal or financial identifiers. Redact or hash identifiers in application logs.

Monitoring delivery

Poll the events endpoint from scheduled automation (READER scope) or export logs to your SIEM. Correlate event IDs with your receiver logs to debug signature mismatches and timeout retries.

See Integration connections for list, create, revoke, and events API paths. Platform alerting webhooks (operator-only) use separate channel configuration under /api/v1/platform/alerting/channels.