Webhooks
Webhooks let your application receive real-time notifications when events occur in Rally CRM. Instead of polling the API, configure an endpoint to receive HTTP POST requests whenever contacts are created, deals change stage, activities are completed, and more.
Endpoints
/api/v1/webhooksList all webhooks/api/v1/webhooksCreate a webhook/api/v1/webhooks/{id}Get webhook details/api/v1/webhooks/{id}Update a webhook/api/v1/webhooks/{id}Delete a webhook/api/v1/webhooks/{id}/testSend a test event/api/v1/webhooks/{id}/deliveriesGet delivery historyCreate Request
CreateWebhookRequest
| Property | Type | Required | Description |
|---|---|---|---|
name | string | ✓ | A descriptive name for the webhook |
url | string | ✓ | The HTTPS endpoint URL that will receive event payloads |
events | List<string> | ✓ | Event types to subscribe to (e.g., contact.created, deal.won) |
Response Model
WebhookResponse
| Property | Type | Required | Description |
|---|---|---|---|
id | Guid | ✓ | Unique webhook identifier |
name | string | ✓ | Webhook name |
url | string | ✓ | Destination endpoint URL |
secret | string | ✓ | HMAC signing secret for verifying webhook payloads |
events | List<string> | ✓ | Subscribed event types |
isActive | bool | ✓ | Whether the webhook is currently active |
lastTriggeredAt | DateTime? | — | Timestamp of the last triggered event |
failureCount | int | ✓ | Consecutive delivery failures (resets on success) |
createdAt | DateTime | ✓ | When the webhook was created |
{
"id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
"name": "CRM Sync",
"url": "https://your-app.com/webhooks/rally",
"secret": "whsec_K7xG9pQ3mN2vR8yT5wB1jL4cF6hD0sA",
"events": [
"contact.created",
"contact.updated",
"deal.stage_changed"
],
"isActive": true,
"lastTriggeredAt": null,
"failureCount": 0,
"createdAt": "2025-02-01T10:00:00Z"
}Available Events
Subscribe to any combination of the following event types when creating or updating a webhook.
| Event | Description |
|---|---|
contact.created | New contact created |
contact.updated | Contact information updated |
contact.deleted | Contact deleted |
company.created | New company created |
company.updated | Company updated |
deal.created | New deal created |
deal.updated | Deal updated |
deal.stage_changed | Deal moved to a new stage |
deal.won | Deal marked as won |
deal.lost | Deal marked as lost |
activity.created | Activity logged |
activity.completed | Activity completed |
Webhook Payload
When an event fires, Rally sends an HTTP POST request to your endpoint with a JSON payload. Every payload includes the event type, a timestamp, and the relevant entity data.
{
"event": "contact.created",
"timestamp": "2025-02-01T10:30:00Z",
"data": {
"id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane@example.com"
}
}Your endpoint should return a 2xx status code within 10 seconds to acknowledge receipt. Failed deliveries are retried with exponential backoff up to 5 times.
Signature Verification
Every webhook request includes an X-Rally-Signature header containing an HMAC-SHA256 hash of the request body, signed with your webhook secret. Always verify this signature to confirm the request originated from Rally.
Verification Steps
- Read the raw request body as a UTF-8 string
- Compute an HMAC-SHA256 hash using your webhook secret as the key
- Hex-encode the result
- Compare with the
X-Rally-Signatureheader value using a constant-time comparison
const crypto = require("crypto");
function verifyWebhookSignature(payload, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(payload, "utf8")
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Express.js example
app.post("/webhooks/rally", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.headers["x-rally-signature"];
const payload = req.body.toString();
if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(payload);
console.log("Received event:", event.event);
// Process the event...
res.status(200).send("OK");
});Examples
Create a Webhook
curl -X POST https://your-tenant.rallycrm.io/api/v1/webhooks \
-H "X-Api-Key: rk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "CRM Sync",
"url": "https://your-app.com/webhooks/rally",
"events": [
"contact.created",
"contact.updated",
"deal.stage_changed",
"deal.won"
]
}'